Semantic Versioning: Difference between revisions
| Line 23: | Line 23: | ||
The major version component is used to indicate backward incompatible [[#Public_API|public API]] changes. | The major version component is used to indicate backward incompatible [[#Public_API|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|public API]]. The major version is set to 1 (and consequently minor and patch versions to 0.0) when the software is first released publicly. From that moment on, the major version is incremented when the a version that comes with backward-incompatible [[#Public_API|public API]] changes is released. When the major version is incremented, the [[#Minor_Version|minor version]] and the [[#Patch_Version|patch version]] are both reset to 0. | 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|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. From that moment on, the major version is incremented when the a version that comes with backward-incompatible [[#Public_API|public API]] changes is released. When the major version is incremented, the [[#Minor_Version|minor version]] and the [[#Patch_Version|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. | Major version numbers are non-negative integers, must not contain extra leading zeroes and it always must increase numerically. | ||
Revision as of 20:48, 3 January 2020
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. 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.
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.
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
Build Metadata
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.