Software Versions

Software versioning plays a critical role in managing the development and release of software products, associating unique identifiers (often a combination of numbers and letters) with each iteration of a software product. This process not only informs users of any changes made to the software, but it also assists Software Quality Assurance teams and Project Managers in identifying any alterations to production code that may have bypassed the established release process. Moreover, versioning allows for the tracing of software changes over time, providing a clear picture of the extent and impact of each update. By maintaining consistency and transparency, software versioning ultimately offers both users and team members a clear understanding of the evolution of the software, contributing to better management, utilization, and trust in the software product.

Software Versioning Outside Jax

Semantic Versioning (SemVer): This approach uses a three-part version number like MAJOR.MINOR.PATCH (for example, 2.3.5). The "major" number changes with incompatible API changes, the "minor" number changes with added functionality in a backwards-compatible manner, and the "patch" number changes with backwards-compatible bug fixes.
Date-based Versioning: This versioning scheme uses dates to mark different versions of the software. For instance, Ubuntu uses this approach, with versions like 21.04, where "21" stands for the year (2021) and "04" stands for the month (April).
Sequence-based Versioning: This approach simply increments the version number with each release, irrespective of the scale of changes. This can be seen in software like Google Chrome, which as of my knowledge cutoff in 2021, is on version 93.
Revision-based Versioning: This approach uses the revision number of the source control system. The version number increments every time a change is committed to the source control repository. Subversion (SVN) is an example of this approach.
"Odd-Even" Versioning: In this scheme, different number sets are used to denote stable and unstable versions of the software. A popular example was the Linux Kernel (before version 3.0), where odd-numbered minor versions (e.g., 2.5.x) were unstable or beta, while even-numbered minor versions (e.g., 2.6.x) were stable.
Unary Number Versioning: This odd approach adds a single digit for every release. TeX famously uses this approach, with versions like 3.14159265. Each release adds a new digit, moving the version number closer and closer to π.

Assigning Version Numbers

Version numbers should be tracked in the source code, and associated with a specific commit. This allows for the software version that is released to be traced back to the source code that was used to build it. It also allows for software builds to be reproducible as the source code can be checked out at the specific commit that was used to build the software.

SQA Supported Versioning Conventions

Semantic Versioning (Default)

Scientific Computing using Semantic Versioning (SemVer) as the default versioning scheme. This approach uses a three-part version number like MAJOR.MINOR.PATCH (for example, 2.3.5).

A version number should be represented as three-part number X.Y. Z, where

X: Major version – This number must be incremented when incompatible Public API changes are made or basic workflow of the software changes.
Y: Minor Version – This number must be incremented when there is new feature/s added or deprecated. The feature changes should be backward compatible.
Z: Patch Version – This number must be incremented when backward compatible bug fixes are done.

SemVer Example

For example, if the version is 1.2.1

Major version 1: There is Public API defined and officially supported
Minor version is 2: There were two new features added after the latest major version release
Patch version is 1: There was one bug fix after the latest minor version release

SemVer Release Cycle

Date Based Versioning

Date based versioning is used when the software is released on a regular basis. The version number is again represented as a three part number X.Y.Z, but the Y number is used to represent the date in one of two ways.

Warning

Date Based versioning is uncommon in Computational Sciences. Before you decide to use this versioning scheme, it's recommended that you discuss it with the SQA team and at a CSSC meeting.

Year/Sprint Versioning

X: Major version – This number must be incremented when incompatible Public API changes are made or basic workflow of the software changes.
Y: Year/Sprint Version – This number tracks the date and sprint increment of the software. For example, if the software is released in the 3rd sprint of 2021, the Y version number will be 20213.
Z: Patch Version – This number must be incremented when backward compatible bug fixes are done.

Year/Sprint Example

If the version number is 1.20224.2

Major version 1: There is Public API defined and officially supported
Year/Sprint version is 20224: The software's release occured in the 4th sprint of 2022
Patch version is 2: There were two bug fixes after the latest year/sprint release

Year/Sprint Release Cycle

Year/Month Versioning

X: Major version – This number must be incremented when incompatible Public API changes are made or basic workflow of the software changes.
Y: Year/Month Version – This number tracks the date of release of the software. For example, if the software is released in the April 2021, the version number will be 20214.
Z: Patch Version – This number must be incremented when backward compatible bug fixes are done.

Year/Month Example

If the version number is 2.20219.3

Major version 1: There is Public API defined and officially supported, and it has been updated once in a non-backwards compatible manner
Year/Sprint version is 20229: The software's release occured in September, 2021
Patch version is 3: There were three bug fixes after the latest year/sprint release