Semantic Version Checker

What makes a version valid

Semantic Versioning 2.0.0 defines a version as MAJOR.MINOR.PATCH, where each field is a non-negative integer with no leading zeroes. 1.2 is not a valid version, 01.2.3 is not either, and the v in v1.2.3 is a tagging convention rather than part of the version itself. Two optional suffixes may follow the patch number.

• Pre-release: a hyphen, then dot-separated identifiers built from ASCII letters, digits and hyphens, as in 1.0.0-alpha.1 or 2.0.0-rc.2. A numeric identifier may not carry a leading zero.
• Build metadata: a plus sign, then dot-separated identifiers from the same character set, as in 1.0.0+build.5. It is ignored entirely when two versions are compared, so 1.0.0+a and 1.0.0+b have equal precedence.

The spec also fixes what each number means: patch for backward-compatible fixes, minor for backward-compatible additions, major for anything that breaks the documented public API. Major version zero is the stated exception, where the API is declared unstable.

Precedence, and where pre-releases sort

Precedence compares major, then minor, then patch, each numerically. When all three are equal, a version carrying a pre-release has lower precedence than the same version without one, because a pre-release is by definition not yet the release. That one rule is why publishing 1.0.0-hotfix after 1.0.0 is never picked up by an installer resolving ^1.0.0.

1. Compare pre-release identifiers left to right, one dot-separated field at a time.
2. A field made only of digits is compared numerically, so alpha.2 sorts below alpha.11.
3. A field containing letters or hyphens is compared in ASCII order.
4. A numeric field always sorts below a non-numeric one.
5. If every shared field is equal, the version with more fields has higher precedence.

Applied to one release train, lowest first, the rules produce the order below. It is the example the specification itself gives.

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

Caret and tilde ranges

The caret allows any release that does not change the left-most non-zero field. That one definition covers every case, including the behaviour people find surprising below 1.0.0. The tilde pins the minor and allows patch releases only.

Two whole ranges separated by a double pipe are an OR, so 1.0.0 || >=2.0.0 matches the one pinned release and everything from 2.0.0 upward, and nothing in between.