This specification describes a set of rules and requirements that dictate how each version identifier 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 to the release or the build take the respective forms -RELEASE.METADATA and +BUILD.METADATA and can be appended to a minimal version identifier.
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.
Pragmatic Versioning MUST be applied only to versionable artifacts that can evolve over time and meet the following requirements.
A versioned artifact MUST comprise a set of features or characteristics that represents a public contract between the publishers and the consumers 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.
The publishers of the artifact MUST declare that it is using Pragmatic Versioning and SHOULD provide a link to this specification.
Example
- This software adheres to Pragmatic Versioning.
The modifications MUST be describable in terms of backwards-compatibility:
Backwards-compatible modifications (also known as internal changes): the outside of the modified artifact is indistinguishable from the unmodified artifact, or interchangeable.
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.
Backwards-incompatible modifications (also known as external changes): the outside of the modified artifact is easily distinguishable from the unmodified artifact, or not completely interchangeable.
Examples
- Renaming a public method of a software library.
- Removing a public class in an API.
Disruptive modifications (also known as structural changes): the modified artifact is totally different from the unmodified artifact, or not at all interchangeable.
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.
The rules that determine the backwards-compatibility level of the modifications MAY depend on the type of the artifact. If the implications are not completely obvious, then the publishers of the artifact SHOULD explain them in detail, next to the declaration of use of Pragmatic Versioning.
Examples
- The document “Requirements Analysis” uses Pragmatic Versioning:
- Fixing typos or styling the document are considered backwards-compatible corrections.
- Adding new optional requirements or recommendations are considered backwards-compatible alterations.
- Rephrasing or altering in any way existing requirements are considered backwards-incompatible changes.
- Adding new requirements or prohibitions, or removing existing ones are considered disruptive changes.
Releases are the only mechanism by which any modifications of the artifact MUST 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, Beta, etc. and they are considered unstable by definition.
Version identifiers are unique, textual values that MUST be assigned to releases so that they can be easily tracked down and distinguished from one another.
A minimal version identifier 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
Each element SHALL either increase numerically or reset to zero.
Examples
1.9.3.5can be bumped to1.9.3.61.9.3.6can be bumped to1.9.4.01.9.4.0can be bumped to1.10.0.01.10.0.0cannot be bumped to1.12.0.01.10.0.0cannot be bumped to1.10.5.51.10.0.0cannot be bumped to1.9.0.0
Identifiers containing both Grade Number and Major Number equal to zero are reserved and MUST NOT be assigned to releases, neither stable nor unstable.
Examples
0.1.0.00.8.0.01.0.0.00.0.0.00.0.0.10.0.1.1
There are two types of metadata that MAY be appended to a minimal version identifier to convey additional information:
[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
[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
Each new release SHALL be assigned to a unique version identifier that will depend on two factors:
Precedence refers to how version identifiers are compared to each other when ordered.
Build Metadata SHOULD be ignored when determining version precedence. Thus two version identifiers 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
Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Grade Number, Major Number, Minor Number and Patch Number are always compared numerically.
Examples
1.0.0.0comes before2.0.0.02.0.0.0comes before2.1.0.02.1.0.0comes before2.1.1.0
When Grade Number, Major Number, Minor Number and Patch Number are equal, a version identifier that includes Release Metadata SHALL have lower precedence than its associated minimal version identifier.
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
The publishers of an artifact are in charge of publishing new releases. Typically they are the ones who develop and integrate corrections and alterations.
Examples
- Maintainers of a software library.
- Authors and editors of a protocol, specification or other type of technical standard.
By adhering to Pragmatic Versioning, they express their commitment to publish new releases with a version identifier that follows the rules described in this specification.
The consumers of a versioned artifact depend on it to achieve their goals. Typically they react to releases by deciding whether to use the new version of the artifact or not.
Examples
- Developers of a software application that depends on a third-party library.
- Implementors of a protocol, specification or other type of technical standard.
They have to be extra careful when backwards-incompatible modifications are introduced, that’s why it is so crucial that published releases follow the rules specified in Pragmatic Versioning.
Backus-Naur form grammar for valid PragVer version identifiers:
<Version Identifier> ::= <Minimal Version Identifier>
| <Minimal Version Identifier> "-" <Release Metadata>
| <Minimal Version Identifier> "+" <Build Metadata>
| <Minimal Version Identifier> "-" <Release Metadata> "+" <Build Metadata>
<Minimal Version Identifier> ::= <Grade Number> "." <Major Number> "." <Minor Number> "." <Patch Number>
<Grade Number> ::= <Number>
<Major Number> ::= <Number>
<Minor Number> ::= <Number>
<Patch Number> ::= <Number>
<Number> ::= "0"
| <Positive Digit>
| <Positive Digit> <Any Numeric Characters>
<Positive Digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<Any Numeric Characters> ::= <Digit>
| <Digit> <Any Numeric Characters>
<Digit> ::= "0" | <Positive Digit>
<Release Metadata> ::= <Metadata>
<Build Metadata> ::= <Metadata>
<Metadata> ::= <Name>
| <Number>
| <Name> "." <Metadata>
| <Number> "." <Metadata>
<Name> ::= <Any Alphanumeric Characters>
<Any Alphanumeric Characters> ::= <Alphanumeric Character>
| <Alphanumeric Character> <Any Alphanumeric Characters>
<Alphanumeric Character> ::= <Digit> | <Letter> | "-"
<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"
The next diagram helps determine which number must be incremented when bumping a new version identifier, by reasoning about the type of modifications that will be released and their backwards-compatibility level:
PCRE for valid PragVer version identifiers:
(?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-])+)*))?