Releases and versioning

Drew Leske

Our policy on releases, release numbering, and versioning is based on semantic versioning and the Python packaging guidelines. For details on how this policy came to be, please visit our blog post on the subject.

  1. We loosely follow semantic versioning. At significant points in development, we assign a version of the format MAJOR.MINOR.PATCH where:

    • MAJOR is either a breaking change in the API, or a significant milestone in functionality and value for the software. The latter does not conform to semantic versioning, though it is not uncommon, and it communicates important information to the users: these are big changes you need to know about, or these are big changes you’ll want to know about, or both.
    • MINOR signifies there are new features which do not break the API or a significant departure in the overall utility of the software.
    • PATCH signifies a release consisting of primarily bug fixes or minor upates.

  2. Releases are primarily expressed through annotated Git tags. The release version is the name of the tag and the changes justifying the release are described in the tag message. The release is reflected in the project’s changelog (CHANGELOG.md) as the version and the changes described in the tag message.

  3. New projects are initially tagged with the version 0.0.0 as part of initialization, such as creation of an empty project README. This is meaningless but establishes a baseline for programatically determining development versions.

  4. Softare packages, container images, and other build outcomes will use the release version, according to their conventions, but the version string itself should be unchanged. For example, if the release version is 1.0.4 for a package “firetruck”, the various build products might be:

    • a container image: firetruck:1.0.4
    • a Python wheel: firetruck-1.0.4-py3-none-any.whl
    • a tarball: firetruck-1.0.4.tar.gz

  5. Version strings for build outcomes of a non-release on the main branch will include the short hash of the commit.

    • Format: <last-release>+<short hash>
    • Example: 1.0.4+22.9100ab3

  6. Version strings for build outcomes on a feature branch will include the short hash of the commit and the branch.

    • Format: <last-release>+<short hash>.<branch>
    • Where: <branch> is the branch name normalized to use the character set [a-zA-Z0-9\.]
    • Example: 1.0.4+22.9100ab3.i88.release.versioning.policy.documentation

References

  1. Semantic version specification (SemVer)
  2. Python Packaging User Guide; its chapter on Versioning