Release versioning#

This section explains how releases are dealt with in the tudat ecosystem.

Learning Objectives

  1. Understand that “dependency hell” exists and how to avoid it.

  2. Understand MAJOR.MINOR.PATCH and when each of them are bumped.

  3. Understand the order of precedence for version labels.

Semantic versioning#

Tom Preston-Werner originally proposed a simple set of rules and requirements that provide a convention for modifying the versioning of software packages [5]. The opening paragraph introduces the concept of dependency hell:

In the world of software management there exists a dreaded place called “dependency hell.” The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair.

This chapter relays the Semantic Versioning (SemVer) 2.0.0 convention in an effort to avoid any developer needed “dependency hell” to be defined. It is further mentioned that the proposed system will only work with an API declaration:

For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number.

The SemVer 2.0.0 can be summarised by the following set of rules: Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards compatible manner, and

  • PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. SemVer only focuses on API compatibility, however there are common labels appended to the semantic version, for example 1.0.0-alpha. The list of requirements for the label formatting are detailed in SemVer. The important takeaway is that precedence is alphanumeric:

Precedence: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta
          < 1.0.0-beta  < 1.0.0-beta.2  < 1.0.0-beta.11
          < 1.0.0-rc.1  < 1.0.0.

Example

A proposed guided example flow is as follows:

  • alpha = in development without caring about (old) unit-tests

  • beta = in development and the old (unit) tests are valid

  • rc.1 = tests for new features are written and valid

  • rc.2 = additional tests had to be written and those were made valid

  • rc.3 = more additional tests that were made valid

However this is just an example flow, not a further set of rules. Depart from it whenever it improves your content.

Break any of these rules sooner than say anything outright barbarous.

—George Orwell, “Politics and the English Language”

Releasing a new version with bumpversion#

Warning

This section is currently only used for releasing new versions of the docs, not of the software. More information about how to release a new version of the software will be provided soon in this page.

Releasing a new version of the documentation is simple. To do this, we rely on bumpversion which in turns uses semantic versioning (see Semantic versioning). Semantic versioning relies the following structure for stable releases: MAJOR.MINOR.PATCH (e.g., 1.3.1). For unstable releases, the same syntax is used with the addition of an additional tag, such as MAJOR.MINOR.PATCH.devBUILD (e.g., 1.3.1.dev2).

Once you have committed your changes, you can release a new version by typing in the terminal one of the following commands:

  • bumpversion patch: this increases the patch number (the same can be done with bumpversion major or bumpversion minor)

    • 1.1.1 -> 1.1.2.dev0

    • 1.1.2.dev0 -> 1.1.3.dev0

    • 1.1.2.dev1 -> 1.1.3.dev0

  • bumpversion dev: this increases the build number

    • 1.1.2.dev0` -> 1.1.2.dev1

    • 1.1.2` -> ❌ This will break. Patch must be bumped to start dev suffix.

  • bumpversion release: this releases a stable version

    • 1.1.2.dev0` -> 1.1.2

    • 1.2.0.dev0` -> 1.2.0

bumpversion creates a dedicated commit every time it is executed and tags such commit with the version number.