Semantic Versioning
External
Internal
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
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. Build metadata is ignored when determining the version precedence: two versions that differ only by build metadata have the same precedence.