Semantic Versioning. Demystifying SemVer and avoiding… | by Donovan Brown | Jun, 2022

Programming Basics

Demystifying SemVer and avoiding “dependency hell”

Chalkboard with 0.1.0 written on it
Version 0.1.0

Last year, I created the video below explaining semantic versioning, but I still meet many people that do not understand how it works. So, in this post, I will explain it to those that prefer to read instead of watch.

YouTube video that explains SemVer

Semantic versioning indicates the type of changes since the last release of a library, as well as if these changes break backward compatibility. This is very important because breaking backward compatibility might require code changes for the consumer.

Semantic versioning has a defined structure and rules that dictate how the version changes. The structure requires a major version (x), followed by a minor version (y), and lastly a patch version (z).

Chalkboard with x.y.z written on it
SemVer structure

Each part is a non-negative integer with no leading zeros. The type of changes since the last version dictate which portion of the version you increment or reset.

Every release should have a unique version. This helps developers easily identify which version individuals were using when they provide feedback or bug reports.

Let’s work through an example starting with version 0.1.0.

Chalkboard with 0.1.0 written on it
Version 0.1.0

Having a major version of zero signifies initial development and that anything may change at any time.

Let’s assume we’re on our third initial release with version 0.3.0.

Chalkboard with 0.3.0 written on it
Version 0.3.0

The next change introduces a backward-compatible bug fix but does not add new functionality. The version of this release must be 0.3.1.

Chalkboard with 0.3.1 written on it
Version 0.3.1

This version informs all consumers that this contains a bug fix and is safe to upgrade to because it contains no breaking changes.

Once I realized that changes in the patch version meant bug fixes, I started updating my libraries more frequently when I saw the patch version change. If I know the release fixes bugs, why would I not upgrade?

When the library developer adds new backward-compatible functionality, the next release must update the minor version to four. The rules of semantic versioning state that all the values to the right of the number incremented must be reset to zero. Therefore, the next version must be 0.4.0.

Chalkboard with 0.4.0 written on it
Version 0.4.0

If the next release only contains backward-compatible bug fixes, the version number must be 0.4.1.

Chalkboard with 0.4.1 written on it
Version 0.4.1

As initial development slows, a developer might want to start getting feedback on what will be version 1.0.0. So, the version number must change to signify to those testing that these are early bits and breaking changes might be introduced before the normal release. This can be done by adding an optional pre-release version.

For example, 1.0.0-rc.2 would indicate a second release candidate.

Chalkboard with 1.0.0-rc.2 written on it
Version with pre-release version number

A pre-release is indicated by appending a hyphen and dot-separated identifiers after the patch version. Identifiers only allow ASCII alphanumeric characters and hyphens. Notice that when the major version was incremented from 0 to 1, all values to the right were reset to 0.

The final optional version that can be added is to build metadata. Build metadata is indicated by appending a plus and dot-separated identifiers after the patch or pre-release version.

Chalkboard with 1.0.0-rc.2+001 written on it
Version with Build metadata

Let’s review the rules assuming a released version 1.0.0. Bug fixes will increment the patch version to 1.0.1. New backward-compatible features will increment the minor version and reset the patch version to 1.2.0. The only time a 2.0.0 version must be released is if changes made will break backward compatibility.

As a consumer of the 1.0.0 release, any 1.x version should be safe. Nevertheless, whenever you make a new version, you should test that your code continues to function as expected. If you’re considering upgrading to a new major version, read the release notes carefully to see what code changes you may have to make.

In this post, we covered the structure of semantic versioning, as well as the rules for when each part should be incremented or reset. You can use this link to the official docs on how precedence is handled when comparing versions.

I encourage everyone that publishes code to help your consumers by implementing semantic versioning.

News Credit

%d bloggers like this: