Versioning

#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 ti 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 final release (see next bullet). 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.

Note that the final release categories are highly-subjective and there may be other considerations such as 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 indicate 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.

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.

#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. This includes an additional field called <relnum> that in general should always be 1. 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. This includes an additional field called <debian-version> that in general should always be 1. 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-1~0.a1
• 3.4.2-1~1.rc1
• 3.5-1

#Example Version Life Cycle

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

Event	Git Tag	RPM Version	Debian Version
A the first alpha for a new major version of the toolkit, 3.5	3.5-0.a1	3.5-0.0.a1	3.5-1~0.a1
A bugfix for the first alpha	3.5-1.a1	3.5-0.1.a1	3.5-1~1.a1
The first release candidate	3.5-2.rc1	3.5-0.2.rc1	3.5-1~2.rc1
A quick bugfix for the first release candidate	3.5-3.rc1	3.5-0.3.rc1	3.5-1~3.rc1
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-1~4.a2
The second release candidate	3.5-5.rc2	3.5-0.5.rc2	3.5-1~5.rc2
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-0.a1	3.5.1-0.0.a1	3.5.1-1~0.a1
A release candidate for 3.5.1	3.5.1-1.rc1	3.5.1-0.1.rc1	3.5.1-1~1.rc1
A final release for 3.5.1	3.5.1	3.5.1-1	3.5.1-1