sajad torkamani

How does semantic versioning work?

12 April 2022 (Updated 25 May 2022)
On this page
What is semantic versioning?
Semantic versioning in action
Version constraints
Notable points in the spec
Sources

What is semantic versioning?

Semantic versioning (sometimes shortened to semver) is a specification that dictates how software packages (those found on NPM, RubyGems, Composer, Nuget, etc.) should use version numbers to convey meaning about the underlying code (e.g., is it beta, alpha, stable?) and what sort of changes are introduced from one version to another (e.g., bug fixes, new functionality, breaking changes, etc.).

In short, it requires packages to use a version in the form MAJOR.MINOR.PATCH and to increment the:

  • MAJOR version when backwards incompatible API changes are released.
  • MINOR version when new functionality / changes that are backwards compatible are released.
  • PATCH version when release backwards compatible bug fixes are released.

Semantic versioning in action

As an example of how semver is used, browse the tags in the Ruby on Rails GitHub project. Here are some example tags:

  • 7.0.0 (Major): much bigger set of changes, including many API changes and deprecations.
  • 6.1.0 (Minor): mostly functionality changes that are backwards-compatible.
  • 6.1.5 (Patch): mostly bug fixes.

Version constraints

Many package managers (e.g., NPM, Composer, RubyGems, etc) let you specify version constraints on package using a standardized syntax.

TypeExampleDescription
Exact version1.0.1Only allow the 1.0.1 version.
Wildcard1.0.*Equivalent to >= 1.0 && < 1.1
Hyphenated range1.0 - 2.0Equivalent to >= 1.0.0 && < 2.1 (range is inclusive of versions on both sides).
Tilde version range~1.2
~1.2.3		Equivalent to >= 1.2.0 && < 2.0.0
Equivalent to >= 1.2.3 < 1.3.0
Caret version range^1.2.3
^0.3		Equivalent to >= 1.2.3 && < 2.0.0
Equivalent to >= 0.3.0 && < 0.4.0

Notable points in the spec

Here‘s the link to the full spec. Notable points are:

  • Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
  • Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Sources

Tagged: Misc