Versioning

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 release take the following sub-forms:
  • 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.
  • Bug Fix and Minor Feature enhancement releases - These contain changes that improve the reliability and stability of the software, but do not add any major new functionality to the user experience.
  • Major Feature enhancement releases - The are releases that add major new functionality and significantly change the user experience (hopefully for the better).
  • Paradigm Shifting Releases - These are earth-shaking changes that fundamentally change the software and user-experience. These likely only happen every few years at most.

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 - If it is a pre-release, and we know the type what release number it is. For example, is it 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 that in general should always be 1. This leads to the following template:

##Debian Packages

#Example Chart