Guide to Semantic Software Versioning

Welcome back to another week of DevOps Insights!

This week, I want to dive into a topic that was an important portion of my time in my previous role: software versioning.

On the surface, you might think of versioning as a trivial matter. In the realm of Software as a Service (SaaS), it may not hold the most importance. However, not all businesses operate under the SaaS model. If your company delivers software to third-party clients who manage it themselves, you'll soon discover that versioning is critical.

Some businesses necessitate rigorous security checks for each new version introduced into their environment. Others are bound by specific compliance requirements, mandating extensive documentation for any software version changes. Even creating a new software version for government clients can involve a meticulous audit process. It might sound unusual, but when dealing with the world's largest vendors, this becomes a reality.

Now that we understand why versioning is vital, let's delve into the specifics.

What is a Version?

You've likely encountered software versions before. Some people pay scant attention to version numbers, focusing more on the changes between versions. This isn't limited to web development; millions of video game enthusiasts eagerly pore over patch notes to understand how updates will affect their gaming experiences. App users routinely check for updates to their smartphone apps, even if they often find nothing more than "bug fixes and improvements."

Breaking Down the Semantic Version Scheme

Let's examine the following version number and dissect its components:

3.16.2-rc.1

The first number, three, represents the major version. Major versions signal compatibility-breaking changes. Bumping this number implies potential backward compatibility issues with, in this instance, 2.x.y versions. Therefore, major version updates are infrequent.

The second number, sixteen, corresponds to the minor version. Minor versions are typically reserved for introducing new features. For instance, adding a new API endpoint to your backend would warrant a minor version update.

The third number, two, denotes the patch (or micro version). This is used for backward-compatible bug fixes. In practice, the patch version is the one most likely to change frequently compared to major and minor versions.

Following the major, minor, and patch numbers, there's a dash. After this dash, you have flexibility to include additional metadata. In this example, I've used "RC," which stands for "release candidate." RC versions are often used for testing, signifying that the software isn't ready for full use yet.

Lastly, there's another number at the end: the build number. Including a build number is valuable as it helps determine whether a build was created before or after another version. For instance, two builds of 3.16.2 without a build number might seem identical, but their build information could be entirely different.

Semantic Versioning in Practice

At my previous company, we adopted the following versioning scheme:

major.minor.patch-build_number.short_git_sha.release_stage

For example: 3.16.2-123.af8gji87.rc

We particularly liked incorporating the build number in this position because it aligns with the apt package manager. Our software was designed for Debian-based operating systems, making this an effective way to deliver new versions without altering the version number. We didn't increment the version for every bug fix, a practice our enterprise clients truly appreciated, as changing versions before the dash triggered audits, whereas modifications to the build number or SHA did not.

Quick Tip: I strongly advise against creating your own scripts to increment version numbers. Nearly every major programming language offers libraries to handle this task, so take advantage of their existing solutions!

In the case of the Helm charts we created, things played out a bit differently. Helm doesn't consider anything after the dash. Therefore, any changes to our Helm charts required a bump in the patch version, a lesson we learned the hard way. ☹️

Conclusion

In conclusion, while software versioning might seem like a minor detail, it carries significant weight. When dealing with businesses that require precision, security, and compliance it can save you time to know the details.

A well-thought out versioning plan will help you avoid chaos and allow you to maintain your software’s version easily. With the help of git triggers and scripting, this work can also be completely automated. Don’t forget to leverage existing solutions to take care of the work for you. This will help you spend more time delivering high-quality software to your clients and less time worried about arbitrary version information!

So, whether you're a developer, a DevOps engineer, or a software architect, mastering the art of versioning is a valuable skill that can elevate your software delivery game and keep your clients satisfied.

If you want to dive deep into the specifications of semantic versioning, I recommend you check it out here. Keep in mind that these are guidelines, not rules. You may adopt all of the guidelines or you can adopt most. Do what is right for your company and for your clients/customers.

I look forward to writing to you again next week!