Versioning

Andrew R. Lake edited this page Apr 5, 2017 · 18 revisions

Overview

It's important to be able to map versions of the source code to operating system specific releases of the software. This makes it easier to track changes, support users, find bugs and apply fixes (to name just a few of the benefits). This document defines a scheme for generating git tags to mark releases of software and mapping those tags to specific packaged releases of the software on supported operating systems.

Types of Releases

Currently perfSONAR has the following types of releases:

  • Pre-Releases - These are releases that are not ready for production but are being tested with the intent of evolving into a specific production-ready release. They take the following forms:
    • Alpha Releases - These are releases used only for internal testing by developers. They should only ever be deployed on internal testbeds.
    • Release Candidates - These are public testing releases. They are not considered production, but allow for the user base to preview and test new releases on a wider scale than internal testing allows.
  • Final Releases - Releases offered to the general public that are considered production quality. These types of releases take the following forms:
    • Paradigm Shifting Releases - These are drastic changes that fundamentally change the software and user-experience. These likely only happen every few years at most.
    • Major Feature Enhancement Releases - These are releases that add major new functionality and significantly change the user experience (hopefully for the better).
    • Bug Fix and Minor Feature Enhancement Releases - These contain changes that improve the stability of the software and/or add minor quality of life features, but do not add any major new functionality to the user experience.
    • Fasttrack Releases - These are releases with fixes that follow an expedited alpha testing track and skip the release candidate phase entirely. This may be due to something as serious as a critical security vulnerability or extremely minor such as an embarrassing typo on a web page.
  • Repackaged releases - These are issued when nothing is changed in the software or any of its dependant files except for the packaging itself.

Note that the final release categories are highly-subjective and there may be other considerations not listed above (e.g. marketing) when categorizing a release. The intent though is to layout the framework that needs to be supported in the tagging and version scheme so once these subjective decisions are made, the code and associated packages can be properly labelled.

Anatomy of Version Numbers

Given the types of releases listed in the previous section, we need to capture the following information in our versioning scheme:

  • Series version - This indicates to which paradigm-shifting release the software belongs. This will be a number starting at 0.
  • Major version - This indicates to which major feature enhancement release the software belongs. This will be a number starting at 0 for each new series version.
  • Minor version - This indicates to which bug fix and minor feature enhancement release the software belongs. This will be a number starting at 0 for each new major version.
  • Patch version - This indicates to which fasttrack release the software belongs. This will be a number starting at 0 for each new minor version if it is a final release OR starting a 0 for with the first pre-release, regardless of type. In a pre-release, the patch number does not reset until the final release. This will provide a means of consistent sorting across package managers while still allowing code to be updated without announcing a brand new release candidate if required.

Additionally for pre-releases we need to know the following:

  • Pre-release type - If this is a pre-release, we need to define whether this is an alpha or release candidate. If it is an alpha release this takes the value a. If it is a release candidate, it takes the value rc.
  • Pre-release number - For a given pre-release type, a number indicating what iteration of that type this is. For example, whether it is the first or second release candidate. This is always a number and starts at 1.

Repackaging releases define one more number depending on the package type:

  • relnum - Is the numbering of the RPM package, incremented only when changes happened in the .spec file.
  • debian-version - Is the numbering of the Debian package, incremented only when changes happened in the /debian/ directory.

Git Tagging

Git tagging is used to mark software as belonging to a particular release. Using the version components in the previous section, tags should take the following forms:

  • If code is for a pre-release (Note: If <minor-version> is 0 it may be excluded. All other values MUST be included regardless of value):

    <series-version>.<major-version>.<minor-version>-<patch-version>.<prerelease-type><prerelease-number>

  • If code is for a final-release (Note: If <patch-version> is 0 it may be excluded. Likewise if BOTH <patch-version> and <minor-version> are 0 then <minor-version> may be excluded as well. All other values MUST be included regardless of value):

    <series-version>.<major-version>.<minor-version>.<patch-version>

Examples:

  • 3.4.1
  • 3.4.1.1
  • 3.4.2-0.a1
  • 3.4.2-1.rc1
  • 3.5

Package Version Numbers

RPMs

RPM version numbers attempt to follow the conventions defined by Fedora for defining pre-releases and final releases. The RPM specific field called <relnum> always start with 1 (so that it is bigger than the 0 used in the pre-release) and should only be incremented whenever changes happens in the .spec file and nowhere else. This leads to the following templates:

  • If code is for a pre-release (Note: If <minor-version> is 0 it may be excluded. All other values MUST be included regardless of value):

    <series-version>.<major-version>.<minor-version>-0.<patch-version>.<prerelease-type><prerelease-number>

  • If code is for a final-release (Note: If <patch-version> is 0 it may be excluded. Likewise if BOTH <patch-version> and <minor-version> are 0 then <minor-version> may be excluded as well. All other values MUST be included regardless of value):

    <series-version>.<major-version>.<minor-version>.<patch-version>-<relnum>

Examples:

  • 3.4.1-1
  • 3.4.1.1-1
  • 3.4.2-0.0.a1
  • 3.4.2-0.1.rc1
  • 3.5-1

Debian Packages

Debian package version numbers attempt to follow the conventions defined by Debian. The Debian specific field called <debian-version> always start with 1 (so that -1 is sorted before than the ~ used in the pre-release) and should only be incremented whenever changes happens in the /debian/ directory and nowhere else. This leads to the following templates:

  • If code is for a pre-release (Note: If <minor-version> is 0 it may be excluded. All other values MUST be included regardless of value):

    <series-version>.<major-version>.<minor-version>~<patch-version>.<prerelease-type><prerelease-number>-<debian-version>

  • If code is for a final-release (Note: If <patch-version> is 0 it may be excluded. Likewise if BOTH <patch-version> and <minor-version> are 0 then <minor-version> may be excluded as well. All other values MUST be included regardless of value):

    <series-version>.<major-version>.<minor-version>.<patch-version>-<debian-version>

Examples:

  • 3.4.1-1
  • 3.4.1.1-1
  • 3.4.2~0.a1-1
  • 3.4.2~1.rc1-1
  • 3.5-1

One can test Debian package version number precedence with the following command (should return 0 if the comparison is true):

dpkg --compare-versions 3.5-1 gt 3.5~4.rc2-1; echo $?

Example Release Life Cycle

Below is a chart that walks through a realistic life cycle for a software release and how the number is reflected in the git tags and various package versions:

Event Git Tag RPM Version Debian Version
The first alpha for a new major version of the toolkit, 3.5 3.5-0.a1 3.5-0.0.a1 3.5~0.a1-1
A bugfix for the first alpha 3.5-1.a1 3.5-0.1.a1 3.5~1.a1-1
The first release candidate 3.5-2.rc1 3.5-0.2.rc1 3.5~2.rc1-1
A quick bugfix for the first release candidate 3.5-3.rc1 3.5-0.3.rc1 3.5~3.rc1-1
A second alpha to test new features that didn't make it into rc1 3.5-4.a2 3.5-0.4.a2 3.5~4.a2-1
The second release candidate 3.5-5.rc2 3.5-0.5.rc2 3.5~5.rc2-1
The final release 3.5 3.5-1 3.5-1
A bugfix for a typo on a web page 3.5.0.1 3.5.0.1-1 3.5.0.1-1
An alpha for a release with large bug fixes and performance improvements, 3.5.1 3.5.1-0.a1 3.5.1-0.0.a1 3.5.1~0.a1-1
A release candidate for 3.5.1 3.5.1-1.rc1 3.5.1-0.1.rc1 3.5.1~1.rc1-1
A final release for 3.5.1 3.5.1 3.5.1-1 3.5.1-1
A Debian repackaging for final release 3.5.1 3.5.1 3.5.1-1 3.5.1-2
An RPM repackaging for final release 3.5.1 3.5.1 3.5.1-2 3.5.1-1
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.