Semantic Versioning (SemVer)
The universal standard for version numbers: MAJOR.MINOR.PATCH. Following these rules helps avoid dependency hell.
When SemVer Matters Most
Semantic versioning matters most when other teams or applications depend on your package, API, or service contract. Clear versioning reduces upgrade risk and makes release notes easier to trust.
The Rules
Given a version number MAJOR.MINOR.PATCH, increment the:
| Key / Code | Description |
|---|---|
| MAJOR version | When you make incompatible API changes (Breaking Changes). |
| MINOR version | When you add functionality in a backward compatible manner. |
| PATCH version | When you make backward compatible bug fixes. |
Examples
| Key / Code | Description |
|---|---|
| 1.0.0 -> 1.0.1 | Bug fix. Safe to upgrade. |
| 1.0.1 -> 1.1.0 | New feature added. Safe to upgrade (should be). |
| 1.1.0 -> 2.0.0 | Breaking change. Update requires code changes. |
| 0.1.0 | Initial development. Anything may change at any time. |
Pre-release Tags
Additional labels can be appended for pre-releases.
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-rc.1 < 1.0.0Common SemVer Mistakes
The most common mistake is shipping breaking behavior in a minor or patch release because the code change looked small. SemVer tracks compatibility impact, not implementation size, so even a one-line breaking change still deserves a major bump.
Related
Pair versioning discipline with tags, releases, and safe history management.
Useful when your release process includes image tags and container version rollouts.
Version schema and application changes carefully when database compatibility matters.
Relevant when API or auth contract changes need explicit versioning strategy.