What Is Semantic Versioning?
Semantic Versioning — commonly abbreviated as SemVer — is a versioning convention defined at semver.org that assigns meaning to version number increments. Instead of arbitrary numbers, each part of a version string communicates a specific type of change to consumers of your software.
The format is: MAJOR.MINOR.PATCH
Breaking Down the Three Components
MAJOR Version
Increment the MAJOR version when you make incompatible API changes. If consumers of your library must change their code to upgrade, it's a major change. Examples include removing a public function, changing a method signature, or restructuring a module's exports.
Example: 1.4.2 → 2.0.0
MINOR Version
Increment MINOR when you add new functionality in a backward-compatible manner. Existing code continues to work; you've simply added more capabilities. New optional parameters, new exported functions, or new configuration options typically qualify.
Example: 1.4.2 → 1.5.0
PATCH Version
Increment PATCH for backward-compatible bug fixes. The API surface is unchanged; you've corrected a defect. Security patches, performance fixes, and corrected edge-case behaviors fall here.
Example: 1.4.2 → 1.4.3
Pre-release and Build Metadata
SemVer supports two optional suffixes:
- Pre-release identifier: appended with a hyphen — e.g.,
1.0.0-alpha.1,2.0.0-rc.3. Signals that the release is unstable and may not satisfy the stated compatibility guarantees. - Build metadata: appended with a plus sign — e.g.,
1.0.0+20250115. Ignored when determining version precedence; used for informational purposes like build timestamps or CI run IDs.
Version 0.x.x — Initial Development
Versions starting with 0 are a special case. A major version of zero signals that the software is in initial development and the public API should not be considered stable. Breaking changes can happen at any time during the 0.x.x phase without incrementing the major version.
SemVer Range Syntax in Package Managers
Most package managers use SemVer ranges in manifest files:
| Range | Meaning |
|---|---|
^1.4.2 | Compatible with 1.4.2 — allows MINOR and PATCH updates |
~1.4.2 | Approximately 1.4.2 — allows PATCH updates only |
>=1.4.0 <2.0.0 | Explicit range |
1.4.2 | Exact version pin |
* | Any version (generally avoid) |
Common Mistakes and How to Avoid Them
- Not incrementing MAJOR for breaking changes. This is the most damaging mistake — it breaks consumers silently. When in doubt, bump the major.
- Using PATCH for new features. Even small additions should be MINOR increments.
- Skipping version numbers. SemVer does not require sequential numbers; you can go from 1.9.0 to 1.10.0 without releasing 1.9.x versions.
- Resetting incorrectly. When MAJOR increments, reset MINOR and PATCH to 0. When MINOR increments, reset PATCH to 0.
Tools That Automate SemVer
Several tools can help automate version management based on commit history:
- semantic-release — fully automates versioning and changelog generation from Conventional Commits
- standard-version — a simpler alternative for local release scripts
- release-please — Google's GitHub Action-based approach
- cargo-release — for Rust crates
Adopting SemVer consistently builds trust with your library's consumers and makes automated tooling like Dependabot and Renovate far more effective at safely updating dependencies in downstream projects.