Semantic Versioning (SemVer) is a standardized versioning scheme that communicates the nature and impact of changes in software releases through a structured three-part version number. It gives developers and consumers a shared contract for understanding compatibility and change severity at a glance.
Semantic Versioning defines version numbers in the format MAJOR.MINOR.PATCH — for example, 2.4.1. Each segment carries a specific meaning: MAJOR signals breaking changes, MINOR signals new backward-compatible features, and PATCH signals backward-compatible bug fixes. The specification is maintained at semver.org and is widely adopted by package ecosystems like npm, Cargo, and PyPI.
Without a versioning contract, consumers of a library cannot safely automate dependency updates — any upgrade could silently break their software. SemVer lets package managers like npm or Cargo resolve compatible version ranges automatically using operators such as ^ (caret) and ~ (tilde). It also creates accountability for library authors to categorize their changes deliberately before releasing.
PATCH (rightmost) increments for bug fixes that do not alter the public API — e.g., 1.0.0 → 1.0.1. MINOR increments when new functionality is added in a backward-compatible way, resetting PATCH to zero — e.g., 1.0.1 → 1.1.0. MAJOR increments when any breaking change is introduced to the public API, resetting both MINOR and PATCH to zero — e.g., 1.1.0 → 2.0.0.
SemVer supports optional pre-release identifiers appended with a hyphen, such as 1.0.0-alpha.1 or 1.0.0-rc.2, which indicate unstable versions with lower precedence than the release. Build metadata can be appended with a plus sign — e.g., 1.0.0+20250101 — but is ignored when determining version precedence. These extensions let teams publish and test candidate versions without polluting the stable release channel.
A MAJOR version of zero (0.y.z) is a special signal that the API is not yet stable and anything may change at any time. During this phase, a MINOR bump may actually introduce breaking changes, so consumers should pin versions tightly. Once an API is ready for production use, the library should graduate to 1.0.0 to begin honoring the full SemVer contract.
The most common mistake is incrementing only PATCH for a change that actually breaks the public API, violating the consumer's trust and potentially breaking builds silently. Always define what constitutes your 'public API' explicitly in documentation so both authors and users agree on what changes trigger each segment. Automate version bumping with tools like semantic-release or Conventional Commits to reduce human error and enforce consistency in CI/CD pipelines.
© RM Full Stack & AI Engineer · All guides · Roadmaps · Open the app