bug: `default_level_bump` no longer working as expected · Issue #1293 · python-semantic-release/python-semantic-release · GitHub

Question

I have a pipeline that builds container images where the code doesn't change often. The images built are tagged with the version derived from python-semantic-release. I would like to ensure that the third digit is always incremented whenever python-semantic-release is called (which it is during the build pipeline).

There is a lack of documentation around what I believe is the relevant configuration option, 'default_bump_level'. It takes an integer but there isn't a description on what the values correlate to. I was testing with default_bump_level = 3 and saw it increment the second digit. Setting it to 2 seemed to increment the patch version. Thinking I had the problem solved I merged it into my pipeline, ran a manual pipeline and it didn't bump the version at all.

I'm guessing maybe the next issue is that I need to wildcard my allowed_tags, but that is just a guess. Would love any help or examples if someone else has any ideas.

Configuration

Semantic Release Configuration

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


[tool.semantic_release.branches.main]
match = "(main|master)"
prerelease = false

[tool.semantic_release.branches."*"]
match = "*"
prerelease_token = "rc"
prerelease = true

[tool.semantic_release.changelog]
exclude_commit_patterns = []
mode = "init"
insertion_flag = "<!-- version list -->"
template_dir = "templates"

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

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

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

[tool.semantic_release.remote]
name = "origin"
type = "gitlab"
# Will look for env GITLAB_TOKEN when type = gitlab
# A Project Access Token should exist with permission to push/tag/release
ignore_token_for_push = false
insecure = false

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

Additional context

My pipeline runs a prepare job that runs semantic-release version to store it as an environmental variable for the later stages to use. This is the output for a manual pipeline run that I expected it to bump from 1.7.0 to 1.7.1.

Created fresh repository.
Checking out 28181a35 as detached HEAD (ref is main)...
Skipping Git submodules setup
Executing "step_script" stage of the job script 00:01
$ git config --global --add safe.directory "$CI_PROJECT_DIR"
$ git checkout -b "$CI_COMMIT_REF_NAME"
Switched to a new branch 'main'
$ git status
On branch main
nothing to commit, working tree clean
$ echo "NEXT_VERSION = $(semantic-release version --print-tag)" >> next_version.env
No release will be made, 1.7.0 has already been released!
$ cat next_version.env
NEXT_VERSION = v1.7.0
Uploading artifacts for successful job 00:01
Uploading artifacts...
next_version.env: found 1 matching artifact files and directories 
Uploading artifacts as "dotenv" to coordinator... 201 Created  
Cleaning up project directory and file based variables 00:00
Job succeeded

I have not included the git log because the intent is to always bump, regardless of what the git log shows.

There is a lack of documentation around what I believe is the relevant configuration option, 'default_bump_level'. It takes an integer but there isn't a description on what the values correlate to. I was testing with default_bump_level = 3 and saw it increment the second digit. Setting it to 2 seemed to increment the patch version.

Yes, the request for adjustment of this configuration option is in #700, but until then the numbers are defined here. It's a problem related to serialization of IntEnums.

it didn't bump the version at all.

I'm not sure why this would have happened. I will have to review the code further.

So I have confirmed that there is a bug here now. I have accidentally broke that functionality here.

Although I have identified this functionality is broken, I personally don't agree with it. It also is a bit weird as with the conventional parser we define only the commit "tags" allowed and what bump it correlates with patch_tags. With this said, what is the purpose of a default bump level (rhetorical)? I actually think we should remove it as it likely is a carry over from before.

Separately, I question the premise of always bumping a version regardless of the type of change created. This forces your user base to update for essentially no user gain especially if you only performed a chore. This concept of deliberate version bumps is the core facet of PSR so providing an always bump version kinda of defeats the purpose. I recommend you take a read at my post and reconsider the always bump concept.

This and your other post mention the user experience. This default bump is needed for that reason in my case. More importantly though it greatly improves the maintenance overhead.

To illustrate how this is the case I need to explain the problem.

I am building containers that are used for executing Ansible content called execution environments. These are "batteries included" images that have many Ansible collections, including system and python dependencies. Some of this content is maintained internally, but most of it is not. Trying to maintain and version locking all the dependencies in git for all this content isn't feasible. That means that an image built last week may be different than the image built the week prior.

It is essential that the version is bumped on every build because the resulting build will almost certainly be different. If semver can't do it, than I'm left with other options which are worse for the users and maintainers. I appreciate that we can differentiate in our semantic versioning between major/minor/patch because there are times that we make more significant changes to the build. I would much rather not have to force trivial commits to kick off a version bump, or switch to using calendar versioning.

I've standardized around python-semantic-version and am using it across several different types of projects. For things outside of container builds, I can see where you're coming from from a philosophical standpoint. Although, I don't think it rules out other approaches such as never changing the main branch without updating the version.

I understand that the challenges I'm describing have technical solutions, but implementing them is non-trivial. I'm trying to drive adoption of versioning content to folks that would not self-identify as developers. Perfection is not the goal, versioning is a new concept and simplicity is king.

I am new to python-semantic-release, considering adopting it for all of my Python package projects. This bug has somehow piqued my interest. I am trying to understand @jeffcpullen's use case:

I am building containers that are used for executing Ansible content called execution environments. These are "batteries included" images that have many Ansible collections, including system and python dependencies. Some of this content is maintained internally, but most of it is not. Trying to maintain and version locking all the dependencies in git for all this content isn't feasible. That means that an image built last week may be different than the image built the week prior.

Ok, so you have a repository which contains some code responsible for building some containers. The code producing these containers requires little to no changes, but the containers it outputs do change. At some point, your pipeline runs python-semantic-release (which is overlooking your code with no changes) and you expect it to come up with the next higher patch version when semantic-release is run because at the end of the whole CI pipeline your software produces slightly different containers than were produced last time. Fair enough. Actually, not fair at all!

My thoughts:

I, too, believe that this intent is a misuse of python-semantic-release, like @codejedi365. What you need here instead is your CI running python-semver rather than python-semantic-release. All you need is a relatively dumb algorithm understanding the semver scheme and knowing what the next patch version should be.
Split it in two git repositories: one for the library code and another for the user-code. In the repository with library code you maintain your code which builds the containers. Here the CI pipline will produce only a new package version of your container-producing software, but no containers. Here you use python-semantic-release and it will produce new version only when your code has had some legitimate changes. The user code repository, on the other hand, a relatively trivial one, can contain but a python script. This script will depend on the current version of your container-producing software. It will only require changes when your library code introduces breaking changes. Here you set up a time-triggered pipeline which checks out your script, installs the current version of your library code and runs the script. New containers will be produced. To assign these containers a version, you shall use python-semver and other data (e.g. the version of the containers built last time) in any way you like to produce a new version string of your liking. Then let the rest of the CI go with that.

I believe it is crucial that you decouple the versioning of your library code from the versioning of the containers as much as possible. In fact I believe that in your case the containers should not even use the semantic versioning scheme at all. If I were you I'd go here with a date-based version, e.g. 2025-46 (year-week), or 2025-08-31 (yyyy-mm-dd). You can still attach the version of your library code which produced it, if you so like: 2025-46+1.2.3. In any case, I recommend you don't use a semantic version for your containers because semantic version exists in order to convey the information about API compatibility (major version, minor version), feature set growth (minor version), and bugfixes (patch version). This does not make sense in your use case with the containers. All you want to tell your customers it that this is the containers they should use this week. Strictly speaking you don't even have to bother with a date-based versioning (although it helps the human memory and thinking). An ever-increasing integer version would be just as functional: v1, v2, v3. But if you really need to stick with some sort of semantic version for the containers so that a package manager easily recognizes them as newer, go with an arbitrarily set major and minor version and bump the patch version.

Also, if you want to stick with your original strategy, you can use the --patch option in the version command to force a patch version bump.

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?

bug: `default_level_bump` no longer working as expected · Issue #1293 · python-semantic-release/python-semantic-release · GitHub

Repository navigation

bug: default_level_bump no longer working as expected #1293

Question

Configuration

Additional context

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

bug: `default_level_bump` no longer working as expected · Issue #1293 · python-semantic-release/python-semantic-release · GitHub

Repository navigation

bug: default_level_bump no longer working as expected #1293

Description

Question

Configuration

Additional context

Activity

codejedi365 commented on Jul 14, 2025

codejedi365 commented on Jul 14, 2025

codejedi365 commented on Jul 16, 2025

jeffcpullen commented on Jul 16, 2025

fleetingbytes commented on Aug 31, 2025

github-actions commented on Nov 30, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions