Repository navigation
Preserve version order when switching prerelease tokens - #498
Open
Apeksha9389 wants to merge 1 commit into
Open
Apeksha9389 wants to merge 1 commit into
Apeksha9389 wants to merge 1 commit into
Conversation
tomschr
requested changes
Oct 18, 2026
tomschr
left a comment
Member
There was a problem hiding this comment.
Hi @Apeksha9389, 👋
thank you very much for submitting this pull request and tackling issue #497! Much appreciated. 😍
Ensuring that Version.next_version("prerelease", prerelease_token=...) preserves monotonic ordering when switching between prerelease tokens is a great improvement and prevents subtle version downgrade bugs.
To help users understand how token transitions work, could you please include a short section and example in docs/usage/increase-parts-of-a-version_prereleases.rst?
Here is the suggested addition:
Documentation change
When switching between prerelease tokens, :meth:`~semver.version.Version.next_version`
preserves natural ordering. Advancing to a higher token retains the patch version,
while switching to an earlier token increments the patch version to prevent a downgrade:
.. code-block:: python
>>> v = Version.parse("1.2.3-alpha.1")
>>> str(v.next_version("prerelease", prerelease_token="beta"))
'1.2.3-beta.1'
>>> str(Version.parse("1.2.3-rc.1").next_version("prerelease", prerelease_token="alpha"))
'1.2.4-alpha.1'Once this is added and the tests pass, this PR should be ready to merge. Thanks again for your contribution! ❤️
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Version.parse("1.2.3-rc.1").next_version("prerelease", "alpha")currently returns1.2.3-alpha.1, which is older than the original version despite the method's ordering guarantee.When resetting the token would move backward, advance the patch version and start the requested prerelease there. This example becomes
1.2.4-alpha.1. Forward changes such asalphatorcretain the patch version, and same-token increments keep their existing behavior. Build metadata is cleared and the original object is unchanged.Fixes #497. This implements the patch-advance option from that issue so valid token changes continue returning a newer version instead of introducing a new exception.
Validation: five regression cases failed before the fix. The full suite now passes 494 tests with one skip and reports 100% coverage. Cases cover legacy counters, numeric tokens, dotted tokens, forward changes and build metadata. One older expectation was updated because it also allowed a backward token change. Documentation and a changelog fragment describe the behavior.
Full Ruff reports 159 existing findings versus 160 on unchanged upstream, with no new findings by file, rule and message. Mypy reports the same missing optional
fast_semver_rs_backendmodule on both trees.git diff --checkpasses. Tested on Python 3.12.AI-assisted implementation and tests.