Semantic versioning

Introduction

Semantic versioning or version semantic management, also referred as Semver is a conventional naming system used to specify the version of a software, a plugin, a library or any other technology with a dot-separated 3 numbers pattern starting from 0 until infinity.

12.345.678

Each digit implies a type of change from the previous version. In order :

1. The first digit stands for a major change
2. The second digit stands for a minor change
3. The third digit stands for a correction or a patch

major.minor.correction

This conventional naming tries to resolve 2 important development issues :

• backwards compatibility : using an operating system as a reference, a new software is backwards-compatible if its N version works with Windows 8 and its N+1 version too. On the opposite, a software isn't backwards-compatible if its N version works with Windows 8 but its N+1 version requires Windows 10.
• dependencies: softwares often rely on other softwares, plugins or libraries to work. For example, a website that can't work before a specific version of a web browser is dependant on the web browser version.

Semantic versioning is often used in combination with version control system (VCS).

3 types of changes

The semantic versioning system consists in incrementing the three digits of the version according to specific rules.

Patch version

from x.x.1 to x.x.2

The patch number x.x.1 is increased to x.x.2 if the changes made are backwards compatible AND if there is no added functionality compared to the previous version. Patches are the most common type of change and may involve subtle changes such as :

• Minor bugs
• Security issues
• Code improvement
• Reduction in execution time
• Etc.

Minor version

From x.1.x to x.2.0

The minor version number is increased from x.1.x to x.2.0 if the changes made are backwards compatible BUT one or more features have been added. Please note that when the minor version is increased, the fix number restarts at 0. Minor changes are quite common, as they often make corrections to user requests for new features, without impacting existing features. For example:

• Being able to add the "middle name" field to an address book, while keeping "first name" and "last name" intact
• Be able to print a document in horizontal mode, while keeping the vertical version intact and as a predefined choice
• Etc.

Translated with www.DeepL.com/Translator (free version)

Major version

From 1.x.x to 2.0.0

The major version number is increased from 1.x.x to 2.0.0 if the changes made create incompatibilities with the previous version, whether due to new features or not. Also in this case, when the major version is increased, the minor version and the fix restarts at 0. Major changes are the least frequent and software developers think carefully before deploying a new major version precisely because it involves dealing with backwards compatibility issues. In the most complex cases, the major version change requires the intervention of the user (be it a "customer" or another developer) to be able to adapt to the new version. Example:

• Imagine an address book that stores contacts in a single "name" field. If the new version splits the address book into "first name" and "last name" and no longer provides a "name" field, it will be necessary to establish how the available data will be split between the new fields.
• Imagine a drawing library that has the drawCircle() and drawSquare() functions. For the sake of consistency, the designers decide to create a draw object with the method circle(), square(), rectangle(), elipse(), etc. The two functions disappear and are replaced by draw.circle() and draw.square().

Other schemes

Semantic versioning makes additional labels available using the three digits.

Alpha version

0.0.x

A software is in alpha version if its first two digits are 0. Software in alpha version is very unstable and backward compatibility is often not guaranteed even if, formally, only the patch digit is changed. Furthermore, an alpha version can be released even if the first digit is greater than 0, because in this case it is an alpha version of a new major release. The nomenclature in this case will be, for example :

2.0.0-alpha.5

Beta version

0.x.x

A software is in beta version if its first number is 0. Beta software is considered to be fairly close to stability, but may still have some bugs or incomplete functionality. As with alpha versions, there may be new major versions of software in beta. The nomenclature, in this case, will be for example :

4.0.0-beta.9

Long Term Support (LTS)

A Long Term Support version of the software means that patches are guaranteed for a given period (often 5 years). For example, if the developers of a software product determine that their 6.5 version is an LTS version, this means that they guarantee the following versions :

• 6.5.1
• 6.5.2
• 6.5.3
• ..
• 6.5.n

that fix bugs or security issues until the end of the specified period. Once this period is over, the version is considered discontinued, therefore no more patches or minor changes will be provided. The decision to consider one version or another as LTS is completely arbitrary and depends on the software developers.

Deprecation

A version, e.g. 1.7.x, is considered to be in deprecation if it is already known that there won't be a 1.8.0 version, and that it will be necessary to upgrade to 2.0.0 (perhaps already existing or in active development) for new features.

Other considerations

The semantic versioning system, as a conventional system, is not always respected. Sometimes developers don't really pay attention to it, but often this is mainly because it is complicated to determine whether a series of changes should be considered as a patch or rather as a minor change.

In addition, one also has to consider the perspective taken in order to estimate the nature of the changes. This can make huge differences depending on whether the perspective is that of the users or the developers. If a software program completely changes its interface, completely reorganises the display of information, but does not - for example - change the structure of the database, this would represent a patch for developers from 1.0.0 to 1.0.1, whereas for users it would represent a change from 1.0.0 to 2.0.0.

Links

• Software versioning (Wikipedia)
• Semantic versioning written by Tom Preston-Werner