What do the numbers in versions mean?
A dependency moves from 1.2.2 to 2.0.0. The first number signals a change that may require adapting your code. How should you read these numbers?
Read MAJOR.MINOR.PATCH
In a version such as 1.2.2, each number has a role if the project follows semantic versioning, or SemVer. This convention describes changes to its public API: documented functions and behaviours that user code can rely on.
- MAJOR increases when the public API changes incompatibly. For example, removing a function used by your application requires changing the code that calls it.
- MINOR increases when functionality is added in a backwards-compatible way. Existing uses continue to work. Marking a public function as deprecated also requires a minor version.
- PATCH increases for backwards-compatible bug fixes. The fix repairs incorrect behaviour while preserving public API compatibility.
Which number should increase in practice?
Here are examples of changes and their version numbers:
1.0.0 → correction de bug compatible → 1.0.1
1.0.1 → nouvelle fonctionnalité compatible → 1.1.0
1.2.2 → changement incompatible → 2.0.0When MINOR increases, PATCH resets to zero. When MAJOR increases, MINOR and PATCH reset to zero. A major release can also contain fixes; an incompatible change is enough to require that level.
From 0.1.0 to 1.0.0
Starting at 0.1.0 suits initial development. While the version remains 0.y.z, SemVer considers the public API liable to change at any time. Moving from 0.2.0 to 0.3.0 may therefore require adapting user code.
Moving to 1.0.0 marks the definition of a stable public API, with a commitment on how its changes are signalled. The product may still have bugs. Stability here refers to the contract users can build their own code on.
Alpha, beta and release candidate
A suffix after a hyphen signals a prerelease: 1.0.0-alpha, 1.0.0-beta or 1.0.0-rc.1. It precedes the corresponding final release and may still be unstable. These versions need evaluation in a test environment before considering production use.
1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0What the + sign means
In 1.0.0+20130313144700, the part after + contains build metadata. It can hold an identifier for finding the corresponding build. This metadata is ignored in version ordering: 1.0.0+build.1 and 1.0.0+build.2 have equal precedence.
Before updating a dependency
These pointers assume the project follows SemVer. A PATCH signals a compatible fix, but a regression remains possible. Before approving the update, read release notes and check journeys that use the dependency. If MAJOR changes, also look for migration instructions. That leaves time to adapt the code before discovering the problem in production on a Friday evening.