Semantic Versioning

External

• https://semver.org
• https://www.infoq.com/news/2017/11/new-version-scheme-java

Internal

• Software Development

Overview

Semantic versioning is attaching meaning to a version label. The version label is used to communicate how the piece of software it is attached to changed in relation to other versions of the same piece of software. The semantic versioning specification comes with a set of rules that dictate how version numbers are assigned and incremented. The essential components of a semantic versioning-compliant version label are:

<major>.<minor>.<patch>[-pre-release-label][+build-metadata]

Concepts

Public API

The semantic versioning-compliant version labels carry meaning about the public API of the piece of software they are attached to. The public API describes how the software is consumed by its clients.

Semantic versioning only works if there is a public API to describe and track by versions - software using semantic versioning MUST declare a public API.

The public API may be a formal code API or simply just documentation that describes how the software works. It is important that the API be clear and precise. Once the public API is declared, changes to it are declared by incrementing the version numbers: major, minor and patch.

Major Version

The major version component is used to indicate backward incompatible public API changes.

The major versions start at 0, which means that the software is in development phase and no guarantees can be made about the stability and the backward compatibility of of the public API. Anything may change at any time, and the public API should not be considered stable.

The major version is set to 1 (and consequently minor and patch versions to 0.0) when the software is first released publicly. Version 1.0.0 define the first public API. From that moment on, the major version is incremented when the a version that comes with backward-incompatible public API changes is released.

When the major version is incremented, the minor version and the patch version are both reset to 0.

Major version numbers are non-negative integers, must not contain extra leading zeroes and it always must increase numerically.

Minor Version

The minor version component is used to indicate backward compatibly functionality additions or changes. To qualify for a minor (and not major) version increase, the change MUST be backward compatible: clients that worked with X.1.10 also work with X.2.0 without noticing. Minor version must be incremented if any public API functionality is marked as deprecated. Minor version may be incremented if substantial new functionality or improvements are introduced in the private code, without affecting the public API.

When the minor version is incremented, the patch version is reset to 0.

Minor version numbers are non-negative integers, must not contain extra leading zeroes and it always must increase numerically.

Patch

The patch version component is used to indicate backward compatibly bug fixes that only affect implementation and do not change the public API in any way. A bug fix is defined as an internal change that fixes incorrect behavior.

Patch version numbers are non-negative integers, must not contain extra leading zeroes and it always must increase numerically.

Versioned Artifact Immutability

https://semver.org/#spec-item-3

Once a versioned package has been released, the contents of that version must not be modified. Any modification must be released as a new version.

Pre-Release Version

A pre-release version is denoted by appending a hyphen and a series of dot-separated identifiers, immediately following the patch version.

1.0.0-CR.1, 1.0.0-Alpha

Pre-releases have a lower precedence than the associated dot version - they indicate that the version is unstable and they might not satisfy the intended compatibility requirements.

Identifiers must include only ASCII alphanumerics and hyphen [0-9A-Za-z-], must not include leading zeroes and must not be empty.

Build Metadata

Build metadata is denoted by appending a plus sign and a series of dot-separated identifiers immediately following the patch or pre-release version. Build metadata must be ignored when determining the version precedence: two versions that differ only by build metadata have the same precedence.

Identifiers must comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-] and must not be empty.

Version Lock

Version lock is a situation that occurs in software development when the specification of the dependencies' version is too tight, so any upgrade of a dependency must be followed by an upgrade release of the dependent package.

Version Promiscuity

Version lock is a situation that occurs in software development when the specification of the dependencies' version is too loose, so an upgrade that introduces a significant, potentially backward incompatible change of a dependency is not reflected by a corresponding upgrade release of the dependent package. Version promiscuity is assuming compatibility with more future versions than is reasonable.

Version Precedence

Precedence refers to how versions are compared to each other when ordered. Version precedence is calculated by separating the version into major, minor, patch and pre-release identifiers, in this order, and comparing the same classes of components. The first difference from left to right determines precedence. Major, minor and patch components are always compared numerically.

Pre-release versions have a lower precedence than their associated normal (dot) version. Precedence for two pre-release versions with the same major, minor, and patch version is determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.

Build metadata is ignored when determining the version precedence: two versions that differ only by build metadata have the same precedence.

1.0.0 < 2.0.0 < 2.1.0 < 2.1.1

2.1.1-1  < 2.1.1

Grammar

<valid semver> ::= <version core>
                  | <version core> "-" <pre-release>
                  | <version core> "+" <build>
                  | <version core> "-" <pre-release> "+" <build>

 <version core> ::= <major> "." <minor> "." <patch>

 <major> ::= <numeric identifier>

 <minor> ::= <numeric identifier>

 <patch> ::= <numeric identifier>

 <pre-release> ::= <dot-separated pre-release identifiers>

 <dot-separated pre-release identifiers> ::= <pre-release identifier>
                                           | <pre-release identifier> "." <dot-separated pre
 <build> ::= <dot-separated build identifiers>
 <dot-separated build identifiers> ::= <build identifier>
                                     | <build identifier> "." <dot-separated build identifie
 <pre-release identifier> ::= <alphanumeric identifier>
                            | <numeric identifier>
 <build identifier> ::= <alphanumeric identifier>
                      | <digits>
 <alphanumeric identifier> ::= <non-digit>
| <non-digit> <identifier characters>
                            | <identifier characters> <non-digit>
                            | <identifier characters> <non-digit> <identifier characters>
<numeric identifier> ::= "0"
                       | <positive digit>
                       | <positive digit> <digits>
<identifier characters> ::= <identifier character>
                          | <identifier character> <identifier characters>
<identifier character> ::= <digit>
                         | <non-digit>
<non-digit> ::= <letter>
              | "-"
<digits> ::= <digit>
           | <digit> <digits>
<digit> ::= "0"
          | <positive digit>
<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
           | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
           | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
           | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
           | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
           | "y" | "z"