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.0.2




Bug Fixes

  • PR #418: Replace OrderedDict with dict.

    The dict datatype is ordered since Python 3.7. As we do not support Python 3.6 anymore, it can be considered safe to avoid OrderedDict. Related to #419.

  • PR #426: Fix replace() method to use the derived class of an instance instead of Version class.

Improved Documentation

  • PR #431: Clarify version policy for the different semver versions (v2, v3, >v3) and the supported Python versions.

  • #432: Improve external doc links to Python and Pydantic.


  • PR #417: Amend GitHub Actions to check against MacOS.

Trivial/Internal Changes

  • PR #420: Introduce ClassVar for some Version class variables, mainly NAMES and some private.

  • PR #421: Insert mypy configuration into pyproject.toml and remove config options from tox.ini.

Version 3.0.1




Tom Schraitle

Bug Fixes

  • #410: Export functions properly using __all__ in

Version 3.0.0




Tom Schraitle

Bug Fixes

  • #291: Disallow negative numbers in VersionInfo arguments for major, minor, and patch.

  • #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 None as token in bump_build() and bump_prerelease().

  • #374: Correct Towncrier’s config entries in the pyproject.toml file. 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

    • Use extend-exclude for flake in setup.cfg` and adapt list.

    • Use skip_install=True in tox.ini for 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.


  • #169: Deprecate CLI functions not imported from semver.cli.

  • #234: In simplified file and remove Tox and Clean classes

  • #284: Deprecate the use of isvalid().

    Rename isvalid() to is_valid() for consistency reasons with is_compatible().

  • PR #290: For semver 3.0.0-alpha0 deprecated:

    • Remove anything related to Python2

    • In tox.ini and .travis.yml Remove targets py27, py34, py35, and pypy. Add py38, py39, and nightly (allow to fail)

    • In simplified file and remove Tox and Clean classes

    • Remove 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

    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 file for the time being until we find a better solution. See #258 for details.


  • #169: Create semver package and split code among different modules in the packages:

    • Remove

    • Create src/semver/

    • Create src/semver/ for all CLI methods

    • Create src/semver/ for the deprecated decorator and other deprecated functions

    • Create src/semver/ to allow calling the CLI using python -m semver

    • Create src/semver/ to hold type aliases

    • Create src/semver/ to hold the Version class (old name VersionInfo) and its utility functions

    • Create src/semver/ for all the metadata variables

  • #213: Add typing information

  • #284: Implement is_compatible() to make “is self compatible with X”.

  • #305: Rename VersionInfo to Version but keep an alias for compatibility

  • PR #359: Add optional parameter optional_minor_and_patch in parse() 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.toml to 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.yml in (not needed anymore)

    • Distinguish between Python 3.6 and others in tox.ini

    • Add skip_missing_interpreters option for tox.ini

    • GH Action: Upgrade setuptools and setuptools-scm and test against 3.11.0-rc.2

Improved Documentation

  • #276: Document how to create a sublass from VersionInfo class

  • #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 Version rename.

  • #312: Rework “Usage” section.

    • Mention the rename of VersionInfo to Version class

    • Remove 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 in example

  • #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 with setup.cfg because the setup.cfg is easier to use

    • Adapt documentation code snippets where needed

    • Adapt tests

    • Changed the deprecated to hardcode the semver package 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.typed to their package supporting typing.”

    Add package_data to setup.cfg to include this marker in dist and whl file.

  • #309: Some (private) functions from the semver.version module has been changed.

    The following functions got renamed:

    • function semver.version.comparator() got renamed to semver.version._comparator() as it is only useful inside the Version class.

    • function semver.version.cmp() got renamed to semver.version._cmp() as it is only useful inside the Version class.

    The following functions got integrated into the Version class:

    • function semver.version._nat_cmd() as a classmethod

    • function semver.version.ensure_str()

  • #313: Correct tox.ini for changelog entry to skip installation for semver. This should speed up the execution of towncrier.

  • #316: Comparisons of Version class and other types return now a NotImplemented constant instead of a TypeError exception.

    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.yml The 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 importlib approach as it doesn’t require to modify sys.path:

  • PR #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.