Skip to content
Antoine Le LouëtIndependent senior developer (Home)
Back to the Journal

Advice3 min read

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?

Versions move from 1.0.0 to 1.0.1 for a fix, then 1.1.0 for a compatible addition and 2.0.0 for an incompatible change.
With SemVer, the number that increases indicates the nature of the change. Original diagram adapted to light and dark themes.

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:

SemVer examples
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.0

When 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.

Version ordering
1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

What 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.

Sources and useful links

Share on LinkedIn (new tab)

Keep reading
All articles in this category