This specification describes a set of rules and requirements that dictate how versions must be bumped and assigned to releases, in a way that communicates the kind of modifications that were done to a versioned artifact.
A minimal version identifier takes the form GRADE.MAJOR.MINOR.PATCH and is bumped by incrementing:
Optional metadata containing additional information associated with the release or the build can be appended, taking the respective forms -RELEASE.METADATA and +BUILD.METADATA.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC 8174 when, and only when, they appear in all capitals, as shown here.
A versioned artifact MUST comprise a set of public features or characteristics that represents a public contract between the publishers and the subscribers of the artifact.
Examples
- A public API, a software package or library in either source code or binary format.
- A text document describing a protocol, specification, or other type of technical standard.
- A database schema, a logical entity–relationship model, or a conceptual data model.
If the implications are not completely obvious, then the publishers of the artifact SHOULD explain them in detail.
Examples
- The document “Requirements Analysis” uses Pragmatic Versioning:
- Fixing typos or styling the document are considered backward-compatible corrections.
- Adding new optional requirements or recommendations are considered backward-compatible alterations.
- Rephrasing or altering in any way existing requirements are considered backward-incompatible changes.
- Adding new requirements or prohibitions, or removing existing ones are considered disruptive changes.
Examples
- Fixing a bug in a software library.
- Removing some typos from a protocol specification.
- Styling the document that defines a technical standard.
Examples
- Adding a new public interface in an API.
- Renaming a local variable in a private method of an application.
- Removing a private method of a software library.
- Marking any public functionality as deprecated.
Examples
- Renaming a public method of a software library.
- Removing a public class in an API.
Examples
- Making a big change of semantics in a software library.
- Changing the paradigm of a software framework.
- A change of the releasing policy.
- A complete overhaul of the codebase.
Versions are unique, textual identifiers composed of a REQUIRED core and an OPTIONAL metadata that MUST be assigned to releases so that they can be clearly tracked down and distinguished from one another.
The core of a version MUST take the form GRADE.MAJOR.MINOR.PATCH where GRADE, MAJOR, MINOR, and PATCH are dot-separated, non-negative integers, and MUST NOT contain leading zeroes.
Examples
1.2.3.48.16.0.643.14.1.5921.02.3.41.2.-3.41.00.3.4
Versions containing both GRADE and MAJOR numbers equal to zero are not valid and MUST NOT be assigned to any releases.
Examples
0.1.0.00.8.0.01.0.0.00.0.0.00.0.0.10.0.1.1
Release metadata MAY be denoted by appending a hyphen - and a series of dot-separated, non-empty identifiers:
[0-9] and MUST NOT include leading zeroes.[0-9A-Za-z-].Examples
1.0.0.0-alpha1.0.0.0-ALPHA.11.2.3.4-1.beta.0.321.2.3.4-SNAPSHOT.128.develop-branch1.0.0.0=alpha.11.0.0.0-alpha;11.0.0.0-@lpha.1
Build metadata MAY be denoted by appending a plus sign + and a series of dot-separated, non-empty identifiers:
[0-9A-Za-z-].Examples
1.0.0.0+linux1.0.0.0-alpha+linux1.2.3.4-beta.512+linux-386.desktop.10241.2.3.4+linux.zaragoza.19980425-1230001.0.0.0#linux1.0.0.0-alpha+linux!1.0.0.0-alpha+linux:386
Precedence refers to how versions are compared to each other when ordered.
Before comparing two versions, they SHALL be split into GRADE, MAJOR, MINOR, PATCH, and release metadata.
Precedence MUST be determined by the first difference when comparing each of the numbers from left to right: GRADE, MAJOR, MINOR, and PATCH.
Examples
1.0.0.0comes before2.0.0.02.0.0.0comes before2.1.0.02.1.0.0comes before2.1.1.0
When the numbers are equal, a version that includes release metadata SHALL have lower precedence.
Examples
1.0.0.0-alphacomes before1.0.0.01.0.0.0-1comes before1.0.0.0
Examples
1.0.0.0-alphacomes before1.0.0.0-alpha.11.0.0.0-alpha.1comes before1.0.0.0-alpha.beta1.0.0.0-alpha.betacomes before1.0.0.0-beta1.0.0.0-betacomes before1.0.0.0-beta.21.0.0.0-beta.2comes before1.0.0.0-beta.111.0.0.0-beta.11comes before1.0.0.0-rc.11.0.0.0-rc.1comes before1.0.0.0
Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.
Examples
1.0.0.0+debian.amd64has the same precedence as1.0.0.0+debian.x861.0.0.0-alpha+100has the same precedence as1.0.0.0-alpha+999
The publishers of an artifact are committed to publishing new releases with a version that follows the rules described in this specification.
Examples
- Maintainers of a software library.
- Authors and editors of a protocol, specification or other type of technical standard.
Publishers of an artifact SHALL be in charge of publishing new releases and MAY also be the ones who develop and integrate corrections and alterations.
Publishers SHOULD strive to publish stable releases.
Publishers MUST declare that they adhere to Pragmatic Versioning and SHOULD provide a link to this specification.
Example
- This software adheres to Pragmatic Versioning.
Releases are the only mechanism by which any modifications of the artifact SHALL be published.
0.1.0.0 (additional metadata MAY be appended).1.0.0.0 (additional metadata MAY be appended).Pre-releases are useful for demonstration and preview purposes before an actual release is published. Typically they have names such as Alpha or Beta. They are considered unstable by definition.
Subscribers of an artifact depend on its releases to achieve their goals and they usually have to be extra careful when backward-incompatible modifications are introduced.
Examples
- Developers of a software application that depends on a third-party library.
- Implementors of a protocol, specification or other type of technical standard.
Subscribers MUST make sure that the versioned artifact adheres to Pragmatic Versioning.
Subscriptions provide a systematic way of finding the most up-to-date release in which a subscriber is interested.
|| selectors.Given a list of released versions of an artifact, the most suitable one MUST be selected as follows:
Selectors help evaluate a list of versions and nominate one possible choice.
Core comparators match versions depending on their core.
&& or whitespace.== is assumed.==VERSION MUST be satisfied by a version whose core has equal precedence to VERSION.
!=VERSION MUST be satisfied by a version whose core has not equal precedence to VERSION.
>VERSION MUST be satisfied by a version whose core has greater precedence than VERSION.
>=VERSION MUST be satisfied by a version whose core has greater than or equal precedence to VERSION.
<VERSION MUST be satisfied by a version whose core has less precedence than VERSION.
<=VERSION MUST be satisfied by a version whose core has less than or equal precedence to VERSION.
FROM_VERSION - TO_VERSION MUST be satisfied by a version whose core has greater than or equal precedence to FROM_VERSION and less precedence than TO_VERSION.
~VERSION MUST be satisfied by a version whose core has greater than or equal precedence to VERSION and less precedence than the result of performing a minor bump on VERSION.
^VERSION MUST be satisfied by a version whose core has greater than or equal precedence to VERSION and less precedence than the result of performing a major bump on VERSION.
A shorthand version is a shortened representation of a version core.
.0 MAY be omitted.Examples
1.2is equivalent to1.2.0.01.2.3is equivalent to1.2.3.01.2.3.41.2.3.4-alpha1.2.3.4+linux
Release comparators allow for the inclusion of some pre-releases.
A list of release comparators MUST be preceded by a hyphen -.
Each release comparator MUST be denoted by a non-empty, dot-separated, textual identifier comprising only alphanumerics and hyphen [0-9A-Za-z-].
A release comparator MUST be satisfied by a version whose release metadata:
Examples
-alphais satisfied by1.2.3.4-alphais satisfied by1.2.3.4+linux-alphais satisfied by1.2.3.4-alpha.foo-alphais not satisfied by1.2.3.4-beta-beta.foois not satisfied by1.2.3.4-beta-beta.foois satisfied by1.2.3.4-beta.foo
Build comparators favor some releases over others, depending on their build metadata.
A list of build comparators MUST be preceded by a plus sign +.
Each build comparator MUST be denoted by a non-empty, dot-separated, textual identifier comprising only alphanumerics and hyphen [0-9A-Za-z-].
A release comparator is always satisfied by any version but it SHALL influence the nomination if and only if there are several versions with the greatest precedence:
Grammars
Backus-Naur Form Grammar for Versions
<Version> ::= <Core> | <Core> "-" <Release> | <Core> "+" <Build> | <Core> "-" <Release> "+" <Build> <Core> ::= <Grade> "." <Major> "." <Minor> "." <Patch> <Grade> ::= <Number> <Major> ::= <Number> <Minor> ::= <Number> <Patch> ::= <Number> <Number> ::= <Digit> | <Positive Digit> <Digits> <Digits> ::= <Digit> | <Digit> <Digits> <Digit> ::= "0" | <Positive Digit> <Positive Digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" <Release> ::= <Metadata> <Build> ::= <Metadata> <Metadata> ::= <Name> | <Number> | <Name> "." <Metadata> | <Number> "." <Metadata> <Name> ::= <Alphanumeric> | <Alphanumeric> <Name> <Alphanumeric> ::= "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" | "-" | <Digit>Backus-Naur Form Grammar for Subscriptions
<Subscription> ::= "" | <Selectors> <Selectors> ::= <Selector> | <Selector> "||" <Selectors> <Selector> ::= <Core Comparators> | <Core Comparators> <Release Comparators> | <Core Comparators> <Release Comparators> <Build Comparators> | <Core Comparators> <Build Comparators> | <Release Comparators> | <Release Comparators> <Build Comparators> | <Build Comparators> <Core Comparators> ::= <Comparator> | <Comparator> "&&" <Core Comparators> | <Comparator> <Core Comparators> <Comparator> ::= <Operator> <Shorthand> | <Shorthand> | <Shorthand> "-" <Shorthand> <Operator> ::= "==" | "!=" | ">" | ">=" | "<" | "<=" | "~" | "^" <Shorthand> ::= <Grade> | <Grade> "." <Major> | <Grade> "." <Major> "." <Minor> | <Grade> "." <Major> "." <Minor> "." <Patch> <Release Comparators> ::= "-" <Names> <Build Comparators> ::= "+" <Names> <Names> ::= <Name> | <Name> "." <Names>
Diagrams
Version Diagram
Core Diagram
Metadata Diagram
Number Diagram
Name Diagram
Subscription Diagram
Shorthand Version Diagram
Operator Diagram
Regular Expressions
PCRE for Versions
(?P<grade>0|[1-9]+\d*)\.(?P<major>0|[1-9]+\d*)\.(?P<minor>0|[1-9]+\d*)\.(?P<patch>0|[1-9]+\d*)(?:-(?P<release_metadata>(?:[A-Za-z0-9-])+(?:\.(?:[A-Za-z0-9-])+)*))?(?:\+(?P<build_metadata>(?:[A-Za-z0-9-])+(?:\.(?:[A-Za-z0-9-])+)*))?PCRE for Subscription:
\s*(?![\s&])(?P<selector>[\s\!\&\+\-\.0-9\<\=\>A-Z\^a-z\~]+(?<![&\s]))\s*(?:$|(?:\|\|\s*(?!$)))PCRE for Selector:
^\s*(?P<core>(?:\s*(?:&&)?\s*(?:(?:(?:\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?)\s*\-\s*(?:\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?))|(?:(?:==|=|!=|>|>=|<|<=|^|~)?\s*(?:\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?))))*)\s*(?:\-\s*(?![\s\.])(?P<release>[\s\-\.0-9A-Za-z]*(?<![\s\.])))?\s*(?:\+\s*(?![\s\.])(?P<build>[\s\-\.0-9A-Za-z]*(?<![\s\.])))?\s*$PCRE for Core Comparators
(?:&&)?(?:(?:(?P<from>\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?)\s*\-\s*(?P<to>\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?))|(?:(?P<op>==|!=|>|>=|<|<=|^|~)?(?P<version>\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?)))PCRE for Release/Build Comparators
\s*(?<name>[\-\dA-Za-z]+)\s*(?:$|\.\s*(?=[^$\s\.]))
The next diagram helps determine which number must be incremented when bumping a new version, by reasoning about the type of modifications that will be released and their backward-compatibility level.
