How does semantic versioning work?

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.

Type	Example	Description
Exact version	1.0.1	Only allow the 1.0.1 version.
Wildcard	1.0.*	Equivalent to >= 1.0 && < 1.1
Hyphenated range	1.0 - 2.0	Equivalent 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

• Semantic Versioning official website
• Versions and constraints – Composer docs