SemVer in a nutshell

Want to keep track of your software project, its releases, its versions and its tags easily and following an industry standard? Enter Semantic Versioning.

SemVer or semantic versioning is a set of rules adopted by the majority of software package publishers, for naming the versions of their packages and modules. As its name indicates (semantics refers to the “meaning” of something), SemVer gives meaning to how we name our versions, as opposed to giving them names willy-nilly.

In this article, we’ll cover the basics of SemVer and how to choose the next version of your package.

Keep in mind that you can follow SemVer with modules, packages, libraries, or even tags for the versions of your projects (like GitHub tags).

Anatomy of a version

Consider version 2.1.0. It consists of 3 numbers separated by dots:

A version number with indications of which number is the major, the minor, and the patch number.

• The first number (2) indicates the major number of the version.
• The second number (1) indicates the minor number of the version.
• The third number (0) indicates the patch number of the version.

So, when do we increase each number?

• We increase the Patch number when the changes released include bug fixes.
• We increase the Minor number when the changes released include new features.
• We increase the Major number when the changes released include breaking changes.

Let’s see this in a table so we can understand it better. Here you’ll see when you should release a patch, a minor, or a major.

╔══════════════════╦═══════╦═══════╦═══════╗
║ Changes contain  ║ Patch ║ Minor ║ Major ║
╠══════════════════╬═══════╬═══════╬═══════╣
║ Bug fixes        ║ Yes   ║ Yes   ║ Yes   ║
║ New features     ║ No    ║ Yes   ║ Yes   ║
║ Breaking changes ║ No    ║ No    ║ Yes   ║
╚══════════════════╩═══════╩═══════╩═══════╝

And how do we increase the version? Consider the version 3.5.8.

• If you increase the patch number… That’s all you need to do: 3.5.9
• If you increase the minor number, you need to reset the patch number to 0: 3.6.0
• If you increase the major number, you need to reset both the minor and patch numbers to 0: 4.0.0

Quick tip

If you’re using NPM you can run the following command to increase the version of your package. Let’s say your current version is 2.5.6:

• npm version patch to increase to the next patch version (2.5.7).
• npm version minor to increase to the next minor version (2.6.0).
• npm version major to increase to the next major version (3.0.0).

This is just a part of SemVer but it’s what you’ll use the majority of the time. For more information on SemVer, check this out.

Examples

You increase the patch number when:

• You fix a piece of code that was breaking the execution of JavaScript.
• You fix a function that didn’t return the correct value.
• You fix a request to the wrong endpoint.
• You fix a visual glitch on your application or one of your components.

You increase the minor number when:

• You created a new component.
• You created a new endpoint.
• You added new functionality to a component, like adding icon support to a TextField component.

You increase the major number when:

• Your bug fix brings breaking changes.
• Your new functionality brings breaking changes.

Here is important to note that you need to worry about breaking changes when you are building and maintaining a library or a component that other developers use. When you change the API of your components, which means that the users of your components will need to make changes to their code, you are introducing breaking changes.

If you are using SemVer to define versions of a product that goes to the final users, the breaking changes you could introduce would be when you remove functionality from your app. Otherwise, you could reserve major releases for big groups of features, a revamp of your user interface, or when it makes sense from a business or marketing perspective.

Thank you for reading!