Semantic Versioning (SemVer) Explained
What you'll learn: How to communicate the nature of changes in your software through a standardized three-part version number.
What is Semantic Versioning?
Semantic Versioning (SemVer) is a version numbering convention that uses a MAJOR.MINOR.PATCH format to convey meaning about what has changed between releases. Instead of arbitrary version numbers, each component signals specific types of changes to consumers of your software.
The MAJOR.MINOR.PATCH Scheme
Think of version numbers like a traffic light system for changes:
-
MAJOR (1.x.x): Increment when you make incompatible API changes. Breaking changes that require users to modify their code. Example:
2.4.1→3.0.0 -
MINOR (x.1.x): Increment when you add backward-compatible functionality. New features that don't break existing code. Example:
2.4.1→2.5.0 -
PATCH (x.x.1): Increment when you make backward-compatible bug fixes. No new features, just fixes. Example:
2.4.1→2.4.2
When to Increment
When releasing:
- Reset lower components to zero when incrementing a higher one (e.g.,
1.4.7→2.0.0, not2.4.8) - Pre-1.0.0 versions signal initial development where anything may change
- Once you hit
1.0.0, you're declaring a public API that follows these rules
Real-World Example
Imagine a payment API:
1.2.3→1.2.4: Fixed a bug in receipt generation (PATCH)1.2.4→1.3.0: Added support for refunds (MINOR)1.3.0→2.0.0: Changed authentication from API keys to OAuth, breaking existing integrations (MAJOR)
Key Takeaway: Semantic Versioning transforms version numbers from arbitrary labels into a communication protocol that tells users whether upgrading will break their code, add features, or simply fix bugs—enabling informed dependency management and release planning.