What the three numbers mean
A semantic version is three non-negative integers joined by dots: MAJOR.MINOR.PATCH, such as 4.17.2. The rules come from the Semantic Versioning 2.0.0 specification. Each position answers one question about the release.
- MAJOR goes up when a change breaks existing callers: removing a function, renaming a field, or changing a default that code relies on.
- MINOR goes up when you add functionality in a backward compatible way, such as a new optional parameter. Marking something as deprecated is also a minor change, as long as it still works.
- PATCH goes up for backward compatible bug fixes that leave the public interface alone.
When one number goes up, every number to its right resets to zero. After 2.4.9, a new feature gives 2.5.0 and a breaking change gives 3.0.0. The numbers are compared as integers, not as text, and they must not have leading zeros, so 1.02.0 is not a valid version.
All of this rests on one requirement: the project must declare a public API, such as the documented functions of a package or the flags of a command line program. Version numbers describe changes to that surface, not to private code.
Versions that start with 0
A major version of zero, as in 0.y.z, means initial development. The specification says anything may change at any time and the API should not be considered stable. Many projects use the minor number as an informal breaking-change signal at 0.x, and package managers assume so (see the caret rules below). Releasing 1.0.0 is the moment you commit to the rules above. If other people already depend on your package in production, it is probably time.
Pre-release labels and build metadata
A hyphen after the patch number starts a pre-release label: dot-separated identifiers made of ASCII letters, digits and hyphens. 1.0.0-alpha, 1.0.0-alpha.1, 2.3.0-rc.2 and 1.0.0-0.3.7 are all valid. A pre-release says the version is not yet stable and might not keep the compatibility promise its number suggests. Numeric identifiers in the label must not have leading zeros either.
A plus sign starts build metadata, for example 1.0.0+001 or 1.0.0-beta+exp.sha.5114f85. It can record a build number or a commit, but it is ignored when deciding which version is newer: 1.0.0+001 and 1.0.0+20130313144700 have equal precedence.
Precedence: which version is higher
Two versions are compared in this order:
- Compare MAJOR, then MINOR, then PATCH as numbers.
1.10.0is higher than1.9.0. - If those are equal, a version without a pre-release label is higher than one with a label.
1.0.0is higher than1.0.0-rc.1. - If both have labels, compare identifiers from left to right. Two numeric identifiers compare as numbers, two alphanumeric identifiers compare in ASCII order, and a numeric identifier is always lower than an alphanumeric one.
- If every identifier so far is equal, the label with more identifiers is higher.
1.0.0-alpha.1is higher than1.0.0-alpha.
Writing those four rules as a small Python comparison function, then sorting a shuffled copy of the example list from the specification, gives this order:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta
< 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0
Look at beta.2 and beta.11. Because 2 and 11 are numeric identifiers they compare as numbers, so 2 comes first. Plain string sorting gets this wrong, and the same trap applies to whole versions. Sorting six versions as text versus by SemVer rules:
as text: 1.10.0, 1.2.0, 1.2.10, 1.2.9, 1.9.0, 2.0.0
SemVer: 1.2.0, 1.2.9, 1.2.10, 1.9.0, 1.10.0, 2.0.0
Caret and tilde ranges
Package managers let a project depend on a range of versions rather than one exact release. The two shorthand operators used by npm, and copied by several other tools, are the caret and the tilde. They are a convention built on top of SemVer, not part of the specification.
The caret ^ allows any change that keeps the left-most non-zero number the same. The tilde ~ allows only patch-level changes when a minor version is given. Each row below was checked by testing the sample versions against the computed bounds:
| Range | Means | Accepts | Rejects |
|---|---|---|---|
^1.2.3 | >=1.2.3 <2.0.0 | 1.2.9, 1.3.0, 1.9.9 | 1.2.2, 2.0.0 |
~1.2.3 | >=1.2.3 <1.3.0 | 1.2.9 | 1.3.0, 1.9.9 |
^0.2.3 | >=0.2.3 <0.3.0 | 0.2.9 | 0.2.2, 0.3.0 |
~0.2.3 | >=0.2.3 <0.3.0 | 0.2.9 | 0.3.0 |
^0.0.3 | >=0.0.3 <0.0.4 | 0.0.3 | 0.0.4 |
The 0.x rows surprise people. ^0.2.3 does not accept 0.3.0, because below 1.0.0 the minor number is treated as the breaking position, and ^0.0.3 shrinks to a single patch. Also, npm ranges skip pre-release versions such as 1.3.0-beta.1 unless the range itself names a pre-release of that same MAJOR.MINOR.PATCH.
Ranges live in a manifest such as package.json, which is ordinary JSON (see JSON syntax). A lockfile then records the exact versions installed, so teammates get the same code.
Deciding which number to bump
Go through these questions for everything that changed since the last release:
- Could any existing, correct use of the public API stop working or behave differently? Removed or renamed items, new required parameters, stricter validation and changed return types all count. If yes, bump MAJOR.
- Did you add something callers can use, or deprecate something? If yes, bump MINOR.
- Otherwise, if you only fixed bugs, made things faster or changed private code, bump PATCH.
Take the highest answer that applies. One breaking change in a release full of fixes still means a major bump. Some cases need care:
- Fixing a bug that users relied on is technically a breaking change. Weigh how widely the old behavior was used, and say clearly in the release notes what changed.
- Dropping support for an old runtime or language version usually counts as breaking, because it can stop a working install.
- Once a version is published, never change its contents. If a release was wrong, publish a new version with the fix.
- Release tags in version control are often written
v2.5.0, but thevis a naming habit, not part of the semantic version. Git basics covers how commits are identified.