# Semantic Versioning Semantic Versioning (SemVer) is a versioning specification co-authored by [[Tom Preston-Werner]] that gives meaning to version numbers. Using the format `MAJOR.MINOR.PATCH`, it communicates the nature of changes: breaking changes increment MAJOR, new features increment MINOR, and bug fixes increment PATCH. This enables developers to understand compatibility at a glance. SemVer emerged to solve "dependency hell"—the difficulty of managing dependencies when version numbers are arbitrary. By encoding compatibility information in the version number itself, package managers can automatically determine safe upgrades. SemVer is now the standard for most package ecosystems including npm, Cargo, pip, and RubyGems. ## Version Format ``` MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD] Examples: 1.0.0 2.1.3 1.0.0-alpha.1 1.0.0-beta+build.123 ``` ## The Rules | Component | Increment When | Example | |-----------|----------------|---------| | MAJOR | Breaking/incompatible API changes | 1.x.x → 2.0.0 | | MINOR | New backwards-compatible features | 1.1.x → 1.2.0 | | PATCH | Backwards-compatible bug fixes | 1.1.1 → 1.1.2 | ## Core Principles 1. **Public API declaration**: Version 1.0.0 defines the public API 2. **MAJOR = 0**: Development phase, anything may change 3. **MAJOR ≥ 1**: Public API is stable 4. **No modifications**: Once released, a version is immutable 5. **Precedence**: 1.0.0 < 1.0.1 < 1.1.0 < 2.0.0 ## Pre-release and Build Metadata - **Pre-release**: `-alpha`, `-beta.1`, `-rc.2` (lower precedence than release) - **Build metadata**: `+build.123`, `+20230615` (ignored in precedence) ``` 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0 < 1.0.1 ``` ## Version Ranges (npm/Cargo style) | Syntax | Meaning | |--------|---------| | `^1.2.3` | ≥1.2.3 and <2.0.0 (compatible) | | `~1.2.3` | ≥1.2.3 and <1.3.0 (patch-level) | | `1.2.x` | Any patch version | | `>=1.0.0` | At least version 1.0.0 | | `1.2.3 - 2.0.0` | Range inclusive | ## Common Mistakes - Incrementing MINOR for breaking changes - Releasing MAJOR 0.x indefinitely - Modifying released versions - Forgetting to reset PATCH when incrementing MINOR ## Adoption SemVer is used by: - **npm**: Node.js packages - **Cargo**: Rust packages - **RubyGems**: Ruby packages - **Go modules**: Go packages - **Composer**: PHP packages - Most modern package managers ## References - https://semver.org (official specification) - https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning ## Related - [[Tom Preston-Werner]] - [[GitHub]] - [[npm]] - [[Version Control]]