Have you ever come across an application version number with the format v1.0.0 and wondered what the numbers 1.0.0 mean?

Description

The numbers 1.0.0 follow a system known as Semantic Versioning (SemVer). In its simplest form, SemVer is a method for tracking changes in an application using the following format:

X       Y       Z
|       |       |
Major   Minor   Patch

Let’s describe each in more detail below.

Major

Major means there’s a breaking change in the application. In other words, updating this number breaks backwards compatability. For this reason, it is generally advised to be extremely cautious when changing this number. For instance, if your team manages a public Application Programming Interface (API), communicate the breaking change to your customers quickly so they can plan for the change without breaking existing functionality. It may help to support the old and new versions simultaneously to allow time for customers to migrate to the new version.

Minor

Minor means there’s a small change in the application. Generally, new features are added as part of a minor release. Unlike bumping the major version, changing this number does NOT break backwards compatability.

Patch

Patch means there’s a small change in the application. Usually, bug fixes are added as part of patch releases. Similar to minor releases, changing this number does NOT break backwards comptability.

With the official definitions out of the way, let’s understand how one can implement SemVer.

Traditionally, organizations use the build IDs in the Continuous Integration (CI) tool for versioning software. This approach comes with a few disadvantages:

1. Generating release versions without the corresponding CI tool becomes difficult in the event the CI tool is unavailable.
2. The build numbers generated by the CI tool are random and hence provide no real value or meaning for the end-user. For instance, two consecutive builds may have the IDs: CI-ab34589c and CI-yue89076.

SemVer can help solve both of the issues highlighted above.

If your team is new to SemVer, implementing it can be daunting task, given the plethora of available options. To simplify and speed up the transition to SemVer, here’s one approach you can take:

1. Choose an application you would like to migrate to using SemVer.
2. Pick the specific tool you will use for SemVer. The following are widely used and available:
   1. Semantic Release using JavaScript
   2. Semantic Release using Go
3. Introduce SemVer by following the steps below:
   1. Compile the application.
   2. Save the compiled artifact. The artifact will be updated.
   3. Run SemVer to generate a new version.
   4. Assign the version generated from step 3 to the artifact saved in step 2.
   5. Validate.
   6. Publish the application.

What We Do

SemVer has significantly helped our team. Here are a few ways in which we have implemented SemVer:

1. Automation: SemVer works best in an environment without any human intervention. i.e., the process of generating a new release number is fully automated.
2. Strict Git commit rules: If your organization currently leverages Git as a version control system, you will notice that the tools mentioned above require good Git commit message etiquette. This means, if you are not doing so already, you will want to look into enforcing strict Git commit rules using something like pre or post commit hooks. This will ensure that the process used to generate a new version using SemVer provides a seamless experience.

Stay tuned. Next time we get into Semantic Commits.