Semantic Versioning

Semantic Versioning (SemVer 2.0.0)

Assign and compare version numbers following the Semantic Versioning 2.0.0 specification, so version changes convey precise meaning about API compatibility.

When to Use

• Deciding the next version number after a set of changes.
• Choosing whether a change is a MAJOR, MINOR, or PATCH bump.
• Tagging a release (git tag vX.Y.Z).
• Adding pre-release identifiers or build metadata.
• Comparing or ordering versions by precedence.
• Validating a version string.

Prerequisite: SemVer requires a declared public API (in code or docs). Bumps are defined relative to changes in that API.

Format

MAJOR.MINOR.PATCH[-prerelease][+buildmetadata]

Each of MAJOR, MINOR, PATCH is a non-negative integer with no leading zeroes (e.g. 1.10.0, never 1.010.0). Once released, a version's contents MUST NOT change — release a new version instead.

Procedure

1. Identify the highest-impact change since the last release.
2. Pick the bump using the decision table below.
3. Reset lower parts to 0 when bumping a higher part (MINOR reset resets PATCH; MAJOR reset resets both MINOR and PATCH).
4. Append pre-release / build metadata if needed (see rules below).
5. Validate the string against the regex, then tag the release:

   git tag -a v1.4.0 -m "Release 1.4.0"
   git push origin v1.4.0
   

   Note: the v prefix is a tag-name convention only — the semantic version itself is 1.4.0, not v1.4.0.

Choosing the Bump

Given a current version X.Y.Z (with X > 0):

Rules:

• MAJOR MUST be incremented for any breaking API change; MAY also include minor/patch changes; MINOR and PATCH reset to 0.
• MINOR MUST be incremented for backward-compatible additions or when marking functionality deprecated; MAY be incremented for substantial internal improvements; PATCH resets to 0.
• PATCH MUST be incremented only for backward-compatible bug fixes (internal changes that fix incorrect behavior).

Initial Development (0.y.z)

• Major version zero (0.y.z) is for initial development — anything MAY change at any time; the public API SHOULD NOT be considered stable.
• Start at 0.1.0 and bump MINOR for each subsequent release.
• Release 1.0.0 once the API is stable / used in production.

Pre-release Versions

Append a hyphen and dot-separated identifiers after PATCH:

• Identifiers MUST be ASCII alphanumerics and hyphens [0-9A-Za-z-], MUST NOT be empty.
• Numeric identifiers MUST NOT include leading zeroes.
• A pre-release has lower precedence than its associated normal version (1.0.0-alpha < 1.0.0).
• Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-rc.1.

Build Metadata

Append a plus sign and dot-separated identifiers after PATCH or pre-release:

• Same character set [0-9A-Za-z-]; identifiers MUST NOT be empty.
• Build metadata MUST be ignored when determining precedence (two versions differing only in build metadata rank equal).
• Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

Precedence (Ordering)

Compare MAJOR, then MINOR, then PATCH numerically. Build metadata is ignored. When core versions are equal, a pre-release ranks lower than the normal version. Between two pre-releases, compare each dot-separated identifier left to right:

1. Numeric-only identifiers compare numerically.
2. Identifiers with letters/hyphens compare lexically in ASCII order.
3. Numeric identifiers always rank lower than non-numeric identifiers.
4. A larger set of pre-release fields ranks higher if all preceding identifiers are equal.

Worked example:

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta
  < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

And core ordering: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.

Validation

Official SemVer regex (ECMAScript / PCRE / Python / Go compatible; capture groups: 1=major, 2=minor, 3=patch, 4=prerelease, 5=buildmetadata):

^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

Quick shell check (GNU grep, PCRE mode):

ver="1.4.2-alpha.1+build.5"
echo "$ver" | grep -Pq '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$' \
  && echo valid || echo invalid

Examples

Key FAQ Points

• Is v1.2.3 a semantic version? No. Prefixing with v is a common tag-name convention; the version is 1.2.3.
• When is 1.0.0? When the software has a stable public API or is used in production.
• Accidentally shipped a breaking change as MINOR/PATCH? Do not modify the released version; release a new version that corrects it, and document the offending version.
• Deprecations? Ship a MINOR release that marks the API deprecated (and document it) before removing it in a later MAJOR release.