Semver

SemVer (Semantic Versioning) uses MAJOR.MINOR.PATCH with optional pre-release and build metadata.

Format

• MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
• Examples: 2.4.1, 1.0.0-beta.2, 1.0.0+20130313144700, 1.0.0-rc.1+exp.sha.5114f85

Meaning

• MAJOR: incompatible API changes.
• MINOR: backward-compatible features.
• PATCH: backward-compatible bug fixes.

Pre-release (-)

• Comes after patch: 1.2.3-alpha.1.
• Dot-separated identifiers; each is numeric (0, 1, ... no leading zeros) or alphanum (alpha, rc).
• Lower precedence than the associated normal version (1.0.0-rc.1< 1.0.0).
• Ordering example:

Build metadata (+)

• Ignored for precedence; for info only. 1.0.0+build.7 == 1.0.0 in ordering.

Precedence rules (sorting)

1. Compare MAJOR, then MINOR, then PATCH numerically.
2. If equal, a version without pre-release wins over one with pre-release.
3. If both have pre-release, compare identifiers left-to-right:

Version bumps

• PATCH: fix bug, no API change. Example: 1.2.3 → 1.2.4.
• MINOR: add backward-compatible functionality. Reset patch to 0. 1.2.3 → 1.3.0.
• MAJOR: break compatibility. Reset minor/patch to 0. 1.2.3 → 2.0.0.
• Stabilizing: drop pre-release when ready. 2.0.0-rc.2 → 2.0.0.

Special case: 0.y.z

• 0.x is initial development; no stability guarantees. Treat any minor bump as potentially breaking.
• Common practice: ^0.y.z behaves more narrowly (see ranges below).

Common range semantics (npm/yarn/pnpm)

• Exact: 1.2.3 → only that version.
• Tilde ~1.2.3 → >=1.2.3 <1.3.0.
• Caret ^1.2.3 → >=1.2.3 <2.0.0.
• Caret with 0:
• Wildcards: 1.2.x or 1.2.* → >=1.2.0 <1.3.0; → any.
• Comparators: >=1.4.0 <2.0.0.
• Hyphen: 1.2.3 - 1.4.5 → >=1.2.3 <=1.4.5.
• Pre-release in ranges is only matched if you explicitly include a pre-release in the comparator (e.g., >=1.0.0-0).

Tag conventions (package registries)

• latest: default stable line.
• next, beta, rc: pre-release channels pointing to specific semver versions.

Rules/constraints

• Identifiers consist of ASCII alphanumerics
• Numeric identifiers have no leading zeros
• No "1.0" vs "1.0.0" ambiguity: valid SemVer uses three numeric components
• Build metadata must follow a + and cannot affect ordering

Practical guidelines

• Keep a CHANGELOG; and document breaking changes clearly
• For libraries, prefer releasing breaking changes in majors, not hidden in minors
• For apps, you may choose stricter internal policies, but version strings should still follow SemVer to set expectations