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 (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.
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.
- Beta Releases - 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:
- Major Releases - These are drastic changes that fundamentally change the software and user-experience. These likely only happen every few years at most.
- Minor Releases - These are releases that add major new functionality and can significantly change the user experience (hopefully for the better).
- Patch Releases - These contain changes that improve the stability of the software and do not contain any new features.
Note that the final release categories contain some subjectivity 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.
The perfSONAR version numbers are based on semantic versioning. Given the types of releases listed in the previous section, we need to capture the following information in our versioning scheme:
- Major version - This indicates to which paradigm-shifting release the software belongs. This will be a number starting at 0.
- Minor version - This indicates to which major 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 bug fix release the software belongs. This will be a number starting at 0 for each new minor version.
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 beta. If it is an alpha release this takes the value a. If it is a beta, it takes the value b.
- 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 beta. 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 is used to mark software as belonging to a particular release. Git tags always start with the letter "v" (see Managing Branches in GitHub). Using the version components in the previous section, tags should take the following forms:
-
If code is for a pre-release:
v<major-version>.<minor-version>.<patch-version>-<prerelease-update-version>.<prerelease-type><prerelease-number>
-
If code is for a final-release:
<major-version>.<minor-version>.<patch-version>
Examples:
- 3.4.1
- 3.4.2-0.a1
- 3.4.2-1.b1
- 3.5.0
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:
<major-version>.<minor-version>.<patch-version>-0.<rerelease-update-version>.<prerelease-type><prerelease-number>
-
If code is for a final-release:
<major-version>.<minor-version>.<patch-version>-<relnum>
Examples:
- 3.4.1-1
- 3.4.2-0.0.a1
- 3.4.2-0.1.b1
- 3.5.0-1
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:
<major-version>.<minor-version>.<patch-version>~<prerelease-update-version>.<prerelease-type><prerelease-number>-<debian-version>
-
If code is for a final-release:
<major-version>.<minor-version>.<patch-version>-<debian-version>
Examples:
- 3.4.1-1
- 3.4.2~0.a1-1
- 3.4.2~1.b1-1
- 3.5.0-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.b2-1; echo $?
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.0 | v3.5.0-0.a1 | 3.5.0-0.0.a1 | 3.5.0~0.a1-1 |
| A bugfix for the first alpha | v3.5.0-1.a1 | 3.5.0-0.1.a1 | 3.5.0~1.a1-1 |
| The first beta | v3.5.0-2.b1 | 3.5.0-0.2.b1 | 3.5.0~2.b1-1 |
| A quick bugfix for the first beta | v3.5.0-3.b1 | 3.5.0-0.3.b1 | 3.5.0~3.b1-1 |
| A second alpha to test new features that didn't make it into beta 1 | v3.5.0-4.a2 | 3.5.0-0.4.a2 | 3.5.0~4.a2-1 |
| The second beta | v3.5.0-5.b2 | 3.5.0-0.5.b2 | 3.5.0~5.b2-1 |
| The final release | v3.5.0 | 3.5.0-1 | 3.5.0-1 |
| A bugfix for a typo on a web page | v3.5.1 | 3.5.1-1 | 3.5.1-1 |
| An alpha for a release with large bug fixes and performance improvements, 3.6.1 | v3.6.1-0.a1 | 3.6.1-0.0.a1 | 3.6.1~0.a1-1 |
| A beta for 3.6.1 | v3.6.1-1.b1 | 3.6.1-0.1.b1 | 3.6.1~1.b1-1 |
| A final release for 3.6.1 | v3.6.1 | 3.6.1-1 | 3.6.1-1 |
| A Debian repackaging for final release 3.6.1 | v3.6.1 | 3.6.1-1 | 3.6.1-2 |
| An RPM repackaging for final release 3.6.1 | v3.6.1 | 3.6.1-2 | 3.6.1-1 |