Changelog version has hardcoded 'v' as prefix even with tag_format = "{version}"

Bug Report

Description

With configuration tag_format = "{version}" instead of the default tag_format = "v{version}", changelog is still been generated with vX.X.X instead of X.X.X

I have found a previous issue had been fixed for the exactly same problem #561 but the code has been refactored since then, and this exactly same issue might be implemented again at here:

python-semantic-release/src/semantic_release/version/version.py

Lines 209 to 210 in eccdb59

    
           def as_semver_tag(self) -> str: 
        
               return f"v{self!s}"

If I understand this correctly, the changelog template revokes this function here with the hardcoded:

python-semantic-release/config/release-templates/.components/versioned_changes.md.j2

Line 11 in eccdb59

release.version.as_semver_tag(),

Expected behavior

When tag_format = "{version}", the changelog's version should format in the same way as {version}.

Actual behavior

When tag_format = "{version}", the changelog's version unexpectedly formats as v{version}.

Environment

Operating System (w/ version): Ubuntu 22.04
Python version: 3.9.13
Pip version: 22.2.2
Semantic-release version: 9.19.1
Build tool (w/ version): N/A

pip freeze

git log --oneline --decorate --graph --all -n 50

Configuration

Semantic Release Configuration

#.semantic-release.toml
[tool.semantic_release]
assets = []
build_command_env = []
commit_message = "{version}\n\nAutomatically generated by python-semantic-release"
commit_parser = "conventional" #
logging_use_named_masks = true #
major_on_zero = true
allow_zero_version = true
no_git_verify = false
tag_format = "{version}" #
version_variables = []

[tool.semantic_release.branches.main]
match = "(main|master|include-prev-changelog)"
prerelease_token = "rc"
prerelease = false

[tool.semantic_release.changelog]
template_dir = "templates"
changelog_file = "CHANGELOG.md"
exclude_commit_patterns = [
    "^(build|chore|ci|style|test)(\\(.*\\))?:.*" #
]
mode = "init"
insertion_flag = "<!-- version list -->"

[tool.semantic_release.changelog.default_templates]
changelog_file = "CHANGELOG.md"
output_format = "md"
mask_initial_release = false

[tool.semantic_release.changelog.environment]
block_start_string = "{%"
block_end_string = "%}"
variable_start_string = "{{"
variable_end_string = "}}"
comment_start_string = "{#"
comment_end_string = "#}"
trim_blocks = false
lstrip_blocks = false
newline_sequence = "\n"
keep_trailing_newline = false
extensions = []
autoescape = true

[tool.semantic_release.commit_author]
env = "GIT_COMMIT_AUTHOR"
default = "semantic-release <semantic-release>"

[tool.semantic_release.commit_parser_options]
other_allowed_tags = ["build", "chore", "ci", "docs", "style", "refactor", "test"]
allowed_tags = ["feat", "fix", "perf", "build", "chore", "ci", "docs", "style", "refactor", "test"]
minor_tags = ["feat"]
patch_tags = ["fix", "perf"]
default_bump_level = 0
parse_squash_commits = false
ignore_merge_commits = false

[tool.semantic_release.remote]
name = "origin"
type = "github"
ignore_token_for_push = false
insecure = false

[tool.semantic_release.publish]
dist_glob_patterns = ["dist/*"]
upload_to_vcs_release = true

Build System Configuration

GitHub Actions Job Definition

Execution Log

semantic-release -c ./.semantic-release.toml -v changelog

Additional context

This is the expected result. Although there is a previous issue and the previous maintainer decided to use the tag format instead. I do not share the same opinion.

The tag format construct is designed for monorepo usage where you have multiple of the same versions but to differentiate you need a different prefix. When you have a monorepo you have multiple changelogs and at that point the prefix is not relevant to the individual modules changelog because the module is a specific semver version. Then separately I believe it looks much better with the v prefix than not in the changelog.

Unlike before, now there is fully customizable changelog templates so my recommendation is to configure custom templates and change the version string to what you desire. Instead you can change it to release.version.as_tag() and it will apply your tag format.

This is the expected result. Although there is a previous issue and the previous maintainer decided to use the tag format instead. I do not share the same opinion.

The tag format construct is designed for monorepo usage where you have multiple of the same versions but to differentiate you need a different prefix. When you have a monorepo you have multiple changelogs and at that point the prefix is not relevant to the individual modules changelog because the module is a specific semver version. Then separately I believe it looks much better with the v prefix than not in the changelog.

Unlike before, now there is fully customizable changelog templates so my recommendation is to configure custom templates and change the version string to what you desire. Instead you can change it to release.version.as_tag() and it will apply your tag format.

Thank you for letting me know this is an expected behavior and the work around. I know this makes sense from monorepo perspective, but I guess people who don't manage monorepo like me would easily expect the other way around.
To only change this prefix by introducing a whole directory of customized template is a bit overkill for this...(I guess it depends on how irritating this would be), I'm ok to comply.
But it would be really great to have a changelog config version_format=as_semver|as_tag to easily switch this around. Let me know if you think this is a good idea, I can help to contribute this.

I know this makes sense from monorepo perspective, but I guess people who don't manage monorepo like me would easily expect the other way around.

Can't say I expected people to remove the v or use tag format for this purpose but yes I see how it could look like that after the fact.

To only change this prefix by introducing a whole directory of customized template is a bit overkill for this

Just note that this line of thinking is a slippery slope for a maintainer as it introduces another variation that I must maintain over the long term. I must consider each variation independently.

But it would be really great to have a changelog config version_format=as_semver|as_tag to easily switch this around. Let me know if you think this is a good idea, I can help to contribute this.

I've considered that it is reasonable to add an configurable option to the default changelog, and would like to add a toggle with the option:

semantic_release.changelog.default_templates.use_tag_format = true | false

Will need to add an E2E test which is most easily accomplished for the repo fixtures that already modify the tag format but the internal changelog generator will need a modification.

In development but has not been completed yet.

It has been 90 days since the last update on this confirmed issue. @python-semantic-release/team can you provide an update on the status of this issue?

Still in backlog

It has been 90 days since the last update on this confirmed issue. @python-semantic-release/team can you provide an update on the status of this issue?

Navigation Menu

Repository navigation

Changelog version has hardcoded 'v' as prefix even with tag_format = "{version}" #1186

Bug Report

Description

Expected behavior

Actual behavior

Environment

Configuration

Execution Log

Additional context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Changelog version has hardcoded 'v' as prefix even with tag_format = "{version}" #1186

Description

Bug Report

Description

Expected behavior

Actual behavior

Environment

Configuration

Execution Log

Additional context

Activity

codejedi365 commented on Feb 14, 2025

drewyangdev commented on Feb 14, 2025

codejedi365 commented on Feb 19, 2025

codejedi365 commented on Apr 22, 2025

github-actions commented on Sep 26, 2025

codejedi365 commented on Oct 1, 2025

github-actions commented on Feb 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions