What is Semantic Versioning?

Has it ever happened to you that you started a project, gave it a version number, let's say 0.0.1, and didn't know how to make it evolve afterwards?

We're used to seeing many software updates go by, but what does it mean to update a dependency from version 15.1.3 to 15.2.1? What do these numbers mean? Are they chosen arbitrarily or does each one have a particular meaning?

Welcome to the world of "Semantic Versioning", also called "SemVer", and its best practices.

SemVer

The goal of Semantic Versioning is to give a unique number to each new version of a piece of software (in the broad sense) in order to be able to identify it, while providing the user with as much information as possible about its changes.

A minimal version identifier that looks like 0.0.1 simply reads as MAJOR.MINOR.PATCH

Major

The "MAJOR" number is the most critical, it's the only one that indicates a change to the API so significant that backward compatibility is no longer guaranteed, thus indicating that this version won't necessarily be compatible with previous versions.

Minor

This number indicates that features have been added (or that features have been deprecated) but that the API remains compatible with older versions.

Patch

This last one indicates that bugs have been fixed but that backward compatibility is guaranteed.

Identifiers and metadata

It is also possible to add additional information to the version code, by adding identifiers to mark the current version as a release or a pre-release, for example.

We would then write: 10.3.6-rc for "release candidate", but we might also find identifiers like alpha or beta, always separated by a dash (hyphen)

Other metadata can be added, such as the internal build number for example, but it must always be preceded by the "+" sign, example: 10.3.6-rc+1452

A few rules to know

There are 11 rules to follow in the version 2.0.0 specification of Semantic Versioning, I won't list them all here, but here are a few that seem important to me:

• The MAJOR, MINOR and PATCH numbers must be positive integers greater than or equal to 0 and must not contain leading zeros (such as 01 or 046).
• A MAJOR number of 0 indicates initial development, so the API can change at any time without this being reflected in the version number. The API must not be considered stable.
• If the MAJOR number is incremented, MINOR and PATCH must be reset to zero, the same applies to PATCH if MINOR is incremented.

Note that the numbers must always be incremented (except for the minor and patch reset), but they don't necessarily have to be linear. It is possible to go from version 1.3.0 to version 1.5.0 to indicate that many features have been added.

I invite you to read the SemVer specification available at https://semver.org/ because it is very well written, accessible, and you'll even find an FAQ there with answers to questions to guide you in your decisions.

To conclude, and as explained in the specification, Semantic Versioning is not a revolutionary idea, and you probably already opt for a similar personal convention. However, strict use of SemVer is essential for functional and robust dependency management.