What is Semantic Versioning (SemVer)?
A version-numbering scheme, MAJOR.MINOR.PATCH, in which each number tells users what kind of change a release contains.
Definition
Semantic Versioning (SemVer) is a specification for assigning version numbers in the form MAJOR.MINOR.PATCH so that the number itself tells consumers what changed. Under SemVer 2.0.0 you increment PATCH for backward-compatible bug fixes, MINOR for backward-compatible new functionality (and when something in the public API is deprecated), and MAJOR for any backward-incompatible change to the public API; the lower numbers reset to zero when a higher one goes up. The scheme only works if the project declares a public API, in code or documentation, because compatibility is judged against it. Version 1.0.0 defines that public API, while 0.y.z is reserved for initial development, where anything may change at any time. A released version must never be modified; any change ships as a new version. Pre-release labels are appended with a hyphen (1.0.0-alpha.1, 2.0.0-rc.1) and rank lower than the normal release, and build metadata after a plus sign (1.0.0+20261023) is ignored when comparing versions. Package managers rely on these rules to decide which upgrades are safe to install automatically.
When to Use Semantic Versioning (SemVer)
SemVer is a promise about your public API, not about how big a release feels. A small change that breaks callers still requires a MAJOR bump, and a large internal rewrite with no API change can be a PATCH. Projects sometimes adopt SemVer partway through their history or change numbering schemes (Gitea dropped its 1. prefix and went from 1.27 to 28.0.0 in 2026), so read a project's own versioning policy before trusting automatic upgrades. Pin exact versions for reproducible builds and use lockfiles, even when ranges allow newer compatible releases.
Semantic Versioning (SemVer) in Practice
- A library goes from 2.3.1 to 2.3.2 after fixing a crash, to 2.4.0 after adding a new optional parameter, and to 3.0.0 after removing a deprecated function.
- Forgejo states it has followed semantic versioning since 7.0.0, so breaking changes only arrive with a new major version such as 16.0 to 17.0, and its container images offer 15 and 15.0 tags for automatic minor or patch upgrades.
- A release candidate is published as 5.0.0-rc.1; it sorts below 5.0.0, so dependency ranges that ask for stable releases do not pick it up.
Common Mistakes
- Shipping a breaking change in a MINOR or PATCH release because it seemed small; consumers with automatic ranges will pick it up and break.
- Republishing different contents under an already-released version number instead of releasing a new version.
- Treating 0.y.z releases as stable: the specification says anything may change at any time before 1.0.0.
- Assuming every project uses SemVer; many use calendar or marketing versions, so check before relying on version ranges.