Change Log¶
Changes for the upcoming release can be found in the “changelog.d” directory in our repository.
This section covers the changes between major version 2 and version 3.
Version 3.1.2¶
- Released:
2026-11-15
- Maintainer:
Tom Schraitle
Deprecations¶
#506: Equality comparisons between
Versioninstances and strings, bytes, tuples, or lists now issue aDeprecationWarningand will be removed in semver 4.Versionremains hashable, but do not mix these types as dictionary keys or set elements during the transition. Convert strings and bytes withparse()and tuples or lists withVersion(*parts).
Trivial Changes¶
#511:
Version.compare()now returns early when both prerelease parts are equal, or when only one version has a prerelease. This makes comparisons and sorting faster.
Version 3.1.1¶
- Released:
2026-11-09
- Maintainer:
Tom Schraitle
Bug Fixes¶
PR #483: Fix
bump_prerelease()andbump_build()to raise aValueErrorwhen thetokenargument is not a valid dot-separated SemVer identifier (for examplebuild+metaorrc.). Previously such tokens were concatenated unchecked, producing version strings thatparse()itself would reject.PR #486: Fix
next_version()to drop the build metadata when incrementing an old-style prerelease without a dot separator (for examplerc3). Previously1.2.3-rc3+build.5became1.2.3-rc4+build.5while1.2.3-rc.3+build.5became1.2.3-rc.4.PR #489:
Version.next_versionnow validates used prerelease tokens and matches token families literally. Invalid tokens raiseValueError. Dotted prefixes advance correctly while existing qualifier chains and legacy counters are preserved.PR #495: The type annotation of
Version.is_valid()now includes its existing support for UTF-8 encoded byte strings.PR #501:
Version.replace()now preserves the original constructorTypeErrorwhen an existing version component receives an invalid value, rather than reporting zero unexpected keyword arguments.PR #508:
Versionsubscripts now accept objects implementing__index__and raiseTypeErrorfor invalid key types.#484: Fix
next_version()to correctly increment old-style prerelease versions without a dot separator (for examplerc3). Previously, callingnext_version("prerelease")on such versions would reset the prerelease number to 1 instead of incrementing it.#487: Comparing versions with long numeric prerelease identifiers no longer raises
ValueErrorbecause of Python’s integer string conversion limit.#497:
Version.next_version("prerelease", prerelease_token=...)now advances the patch version when switching tokens would otherwise produce a lower version. For example, switching from1.2.3-rc.1toalphareturns1.2.4-alpha.1. Forward token changes retain the current patch version.#499:
Version.next_version("prerelease")now advances the patch version when incrementing an old-style prerelease counter would produce an older version. For example,1.2.3-rc9becomes1.2.4-rc10. The legacy token and incremented counter are preserved; increments that already move forward keep the current patch version.
Trivial Changes¶
PR #502: Add tests for six behaviours that mutation testing showed were not covered:
match()at the boundary version, build metadata inis_compatible(), numeric-only prereleases inbump_prerelease(), the pysemver return code for an invalid version, and thedeprecated()messages.
Version 3.1.0¶
- Released:
2026-09-12
- Maintainer:
Tom Schraitle
Bug Fixes¶
PR #478:
Version.parse()andVersion.is_valid()now reject non-ASCII digits and trailing newlines, in accordance with the SemVer grammar. Optional minor and patch parsing applies the same character restrictions.PR #479: Comparing a
Versionwith adict,tuple, orlistthat cannot construct a valid version (for example, an empty collection, wrong number of parts, non-numeric parts, or unknown keys) no longer raises internal errors fromVersion.__init__. The comparison operators now returnNotImplementedfor such operands, following the general rule for invalid comparison operand types: equality evaluates toFalseand ordering raises Python’s standardTypeError(for example,'>' not supported between instances of 'Version' and 'dict').PR #480: (
bump_build()) will now add.0to an existing build when the last segment of the current build metadata, split by dots (.), is not numeric. This is to ensure the bumped version contains a raised build instead of silently returning an unchanged version. For example,1.2.3+alphais bumped to1.2.3+alpha.0. This mirrors the corresponding fix for the prerelease part (#460). Related to #466.#460:
bump_prerelease()will now add .0 to an existing prerelease when the last segment of the current prerelease, split by dots (.), is not numeric. This is to ensure the new prerelease is considered higher than the previous one.bump_prerelease()now also support an argument bump_when_empty which will bump the patch version if there is no existing prerelease, to ensure the resulting version is considered a higher version than the previous one.
Features¶
PR #476: Added optional
[native]extra to accelerate parsing on CPython via thefast-semver-rs-backendpackage. The pure-Python parser remains the default; the native backend is opt-in and only available on CPython.
Internal Changes¶
: Update GitHub Actions for astral-sh/setup-uv (version 0.10.1), github/codeql-action (version 4)
Trivial Changes¶
#463: Remove double code in
Version.bump_build()
: Improve test coverage to 100% by ignoring the optional Rust backend fallback.
: Improve test suite for comparisons and fix test coverage.
: Suppress deprecation warnings in test suite.
Version 3.0.4¶
- Released:
2025-01-24
- Maintainer:
Tom Schraitle
Bug Fixes¶
Version 3.0.3¶
- Released:
2025-01-18
- Maintainer:
Tom Schraitle
Bug Fixes¶
PR #453: The check in
_comparatordoes not match the check inVersion.compare(). This breaks comparision with subclasses.
Improved Documentation¶
PR #435: Several small improvements for documentation:
Add meta description to improve SEO
Use canonicals on ReadTheDocs (commit 87f639f)
Pin versions for reproducable doc builds (commit 03fb990)
Add missing
.readthedocs.yamlfile (commit ec9348a)Correct some smaller issues when building (commit f65feab)
PR #436: Move search box more at the top. This makes it easier for users as if the TOC is long, the search box isn’t visible anymore.
Features¶
PR #439: Improve type hints to fix TODOs
Internal Changes¶
PR #440: Update workflow file
PR #446: Add Python 3.13 to GitHub Actions
PR #447: Modernize project configs with
pyproject.tomland use Astral’s uv command.In
pyproject.toml:Move all project related data from
setup.cfgtopyproject.tomlUse new dependency group from PEP 735
Consolidate flake8, isort, pycodestyle with ruff
Split towncrier config type “trivial” into “trivial” and “internal”
Create config file for ruff (
.ruff.toml)Create config file for pytest (
.pytest.ini)Simplify
tox.iniand remove old stuffDocument installation with new uv command
Simplify Sphinx config with
find_version()Update the authors
Use uv in GitHub Action
python-testing.ymlworkflow
Update
release-procedure.md.PR #451: Turn our Markdown issue templates into YAML
Trivial Changes¶
Version 3.0.2¶
- Released:
2023-10-09
- Maintainer:
Tom Schraitle
Bug Fixes¶
Improved Documentation¶
Features¶
PR #417: Amend GitHub Actions to check against MacOS.
Trivial/Internal Changes¶
Version 3.0.1¶
- Released:
2023-06-14
- Maintainer:
Tom Schraitle
Bug Fixes¶
#410: Export functions properly using
__all__in__init__.py.
Version 3.0.0¶
- Released:
2023-04-02
- Maintainer:
Tom Schraitle
Bug Fixes¶
#291: Disallow negative numbers in VersionInfo arguments for
major,minor, andpatch.#310: Rework API documentation. Follow a more “semi-manual” attempt and add auto directives into
docs/api.rst.#344: Allow empty string, a string with a prefix, or
Noneas token inbump_build()andbump_prerelease().#374: Correct Towncrier’s config entries in the
pyproject.tomlfile. The old entries[[tool.towncrier.type]]are deprecated and need to be replaced by[tool.towncrier.fragment.<TYPE>].PR #384: General cleanup, reformat files:
Reformat source code with black again as some config options did accidentely exclude the semver source code. Mostly remove some includes/excludes in the black config.
Integrate concurrency in GH Action
Ignore Python files on project dirs in .gitignore
Remove unused patterns in MANIFEST.in
Use
extend-excludefor flake insetup.cfg`and adapt list.Use
skip_install=Trueintox.inifor black
PR #393: Fix command python -m semver to avoid the error “invalid choice”
PR #396: Calling
parse()on a derived class will show correct type of derived class.
Deprecations¶
#169: Deprecate CLI functions not imported from
semver.cli.#234: In
setup.pysimplified file and removeToxandCleanclasses#284: Deprecate the use of
isvalid().Rename
isvalid()tois_valid()for consistency reasons withis_compatible().PR #290: For semver 3.0.0-alpha0 deprecated:
Remove anything related to Python2
In
tox.iniand.travis.ymlRemove targets py27, py34, py35, and pypy. Add py38, py39, and nightly (allow to fail)In
setup.pysimplified file and removeToxandCleanclassesRemove old Python versions (2.7, 3.4, 3.5, and pypy) from Travis
#372: Deprecate support for Python 3.6.
Python 3.6 reached its end of life and isn’t supported anymore. At the time of writing (Dec 2022), the lowest version is 3.7.
Although the poll didn’t cast many votes, the majority agreed to remove support for Python 3.6.
- PR #402: Keep
semver.compare. Although it breaks consistency with module level functions, it seems it’s a much needed/used function. It’s still unclear if we should deprecate this function or not (that’s why we use
PendingDeprecationWarning).As we don’t have a uniform initializer yet, this function stays in the
_deprecated.pyfile for the time being until we find a better solution. See #258 for details.
- PR #402: Keep
Features¶
#169: Create semver package and split code among different modules in the packages:
Remove
semver.pyCreate
src/semver/__init__.pyCreate
src/semver/cli.pyfor all CLI methodsCreate
src/semver/_deprecated.pyfor thedeprecateddecorator and other deprecated functionsCreate
src/semver/__main__.pyto allow calling the CLI using python -m semverCreate
src/semver/_types.pyto hold type aliasesCreate
src/semver/version.pyto hold theVersionclass (old nameVersionInfo) and its utility functionsCreate
src/semver/__about__.pyfor all the metadata variables
#213: Add typing information
#284: Implement
is_compatible()to make “is self compatible with X”.#305: Rename
VersionInfotoVersionbut keep an alias for compatibilityPR #359: Add optional parameter
optional_minor_and_patchinparse()to allow optional minor and patch parts.PR #362: Make
match()accept a bare version string as match expression, defaulting to equality testing.#364: Enhance
pyproject.tomlto make it possible to use the pyproject-build command from the build module. For more information, see Building semver.#365: Improve
pyproject.toml.Use setuptools, add metadata. Taken approach from A Practical Guide to Setuptools and Pyproject.toml.
Doc: Describe building of semver
Remove
.travis.ymlinMANIFEST.in(not needed anymore)Distinguish between Python 3.6 and others in
tox.iniAdd skip_missing_interpreters option for
tox.iniGH Action: Upgrade setuptools and setuptools-scm and test against 3.11.0-rc.2
Improved Documentation¶
#276: Document how to create a sublass from
VersionInfoclass#284: Document deprecation of
isvalid().PR #290: Several improvements in the documentation:
New layout to distinguish from the semver2 development line.
Create new logo.
Remove any occurances of Python2.
Describe changelog process with Towncrier.
Update the release process.
#304: Several improvements in documentation:
Reorganize API documentation.
Add migration chapter from semver2 to semver3.
Distinguish between changlog for version 2 and 3
#305: Add note about
Versionrename.#312: Rework “Usage” section.
Mention the rename of
VersionInfotoVersionclassRemove semver. prefix in doctests to make examples shorter
Correct some references to dunder methods like
__getitem__(),__gt__()etc.Remove inconsistencies and mention module level function as deprecated and discouraged from using
Make empty
super()call insemverwithvprefix.pyexample
#315: Improve release procedure text
#335: Add new section “Converting versions between PyPI and semver” the limitations and possible use cases to convert from one into the other versioning scheme.
#340: Describe how to get version from a file
#343: Describe combining Pydantic with semver in the “Advanced topic” section.
#350: Restructure usage section. Create subdirectory “usage/” and splitted all section into different files.
#351: Introduce new topics for:
“Migration to semver3”
“Advanced topics”
PR #392: Fix the example in the documentation for combining semver and pydantic.
Trivial/Internal Changes¶
#169: Adapted infrastructure code to the new project layout.
Replace
setup.pywithsetup.cfgbecause thesetup.cfgis easier to useAdapt documentation code snippets where needed
Adapt tests
Changed the
deprecatedto hardcode thesemverpackage name in the warning.
Increase coverage to 100% for all non-deprecated APIs
PR #290: Add supported Python versions to black.
#304: Support PEP-561
py.typed.According to the mentioned PEP:
“Package maintainers who wish to support type checking of their code MUST add a marker file named
py.typedto their package supporting typing.”Add package_data to
setup.cfgto include this marker in dist and whl file.#309: Some (private) functions from the
semver.versionmodule has been changed.The following functions got renamed:
function
semver.version.comparator()got renamed tosemver.version._comparator()as it is only useful inside theVersionclass.function
semver.version.cmp()got renamed tosemver.version._cmp()as it is only useful inside theVersionclass.
The following functions got integrated into the
Versionclass:function
semver.version._nat_cmd()as a classmethodfunction
semver.version.ensure_str()
#313: Correct
tox.iniforchangelogentry to skip installation for semver. This should speed up the execution of towncrier.#316: Comparisons of
Versionclass and other types return now aNotImplementedconstant instead of aTypeErrorexception.The NotImplemented section of the Python documentation recommends returning this constant when comparing with
__gt__,__lt__, and other comparison operators to “to indicate that the operation is not implemented with respect to the other type”.#319: Introduce stages in
.travis.ymlThe config file contains now two stages: check and test. If check fails, the test stage won’t be executed. This could speed up things when some checks fails.#322: Switch from Travis CI to GitHub Actions.
#347: Support Python 3.10 in GitHub Action and other config files.
#378: Fix some typos in Towncrier configuration
#388: For pytest, switch to the more modern
importlibapproach as it doesn’t require to modifysys.path: https://docs.pytest.org/en/7.2.x/explanation/pythonpath.htmlPR #389: Add public class variable
Version.NAMES.This class variable contains a tuple of strings that contains the names of all attributes of a Version (like
"major","minor"etc).In cases we need to have dynamical values, this makes it easier to iterate.