Best Practices When Versioning a Release

Ever wondered how to version a release of your software? Ever looked around at the software you’re using and asked what their approach is, or whether you should use it? Have you ever been confused as to which approach to take?

I get it, software, like any complex human endeavor, isn’t easy; and release versioning is no different. What’s more, it may not seem obvious at first, but the way you version your software has a significant impact on how people use it and what they think about it.

For example, here are questions users (or systems administrators) may typically ask:

• Am I on the latest version?

• Do I have to upgrade?

• Do I have the most recent security patches?

As a software developer, these may seem like trivial questions. However, as a user -- especially if they're a systems administrator for a larger organization -- they’re not.

This fact was highlighted to me recently by a client. We got to talking about release versioning and they remarked that you have to be careful of your release naming convention and how often you release a new version.

Why? you may be asking. Well, consider this scenario: A user purchased and installed version 8 of your software some months ago, and recently you released a new, major version. However, instead of naming it version 9, you name it 9.1. Even worse, you gave it a human name or skipped several versions, say to version 14.

Internally, in your software team, you know what’s going on and what things mean. But walk a moment in the user’s shoes. Here’s what they may be (and likely are) asking themselves:

• Have I missed several versions?

• Do I have to pay (again) to update to the new release, because my current version is now out of date by potentially several versions?

• If the upgrade is necessary, because of the large jump in version numbers, will I risk losing my (precious) data because of significant structural changes?

• What kind of disruption will upgrading mean to my business?

Perhaps I’m going over the top here. Yet I need to stress that naming is important. If you get it right, you give your users what all of us want: consistency, predictability, and transparency.

When we do these things right, you get trust in return: trust that your software, instead of a competitor’s, is the right one for them to invest in; trust that the price is justified; trust that you know what you’re doing.

Trust is priceless!

So, if you’re not sure about a versioning style for your software, I want to show you an industry best practice; it’s called semantic versioning.

The name might be new to you, but you’ve likely seen it countless times. Here are three examples. At the time of writing, Google Chrome is at version 63.0.3239.132, Firefox is at version 57.0.4, and Mac Mail is at version 11.2. These three are examples of semantic versioning.

Quoting semver.org, semantic versioning works like this:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards-compatible manner, and PATCH version when you make backwards-compatible bug fixes.

Additional labels for prerelease and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Let’s put that into context with some concrete examples. At the time of writing:

• Firefox is at version 57.0.4. That means that it’s on the fourth patch to its 57th major release.

• Google Chrome is at version 63.0.3239. That shows that it’s on the 3,239th patch to version 63.

• Mac Mail is at version 11.2. That means that it’s on the second minor update to version 11.

From these three examples, you can see that semantic versioning is a very concise and structured system for versioning a release. To be fair, there’s a number of further rules in addition to what I’ve covered here. However, these are the basics.

Yet, even with a naming system this concise, there are still some glaring questions to answer, such as the following two, from the semantic versioning FAQ:

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backward compatibility, you should probably already be 1.0.0.

!Sign up for a free Codeship Account

Those questions aside, now that we’ve learned the fundamentals of semantic versioning, there are five core considerations that you need to keep in mind when using it.

Make sure that you communicate to your users that you’re using semantic versioning, what it means, and where they can find further information about it.

This is especially important if your users are a mix of technical and non-technical. The more technical they are, the more likely (but not guaranteed) it will be, that they will understand what it means.

However, for the less technical (or more casual) user, the naming style may not be as clear to them -- at least at first. So let them know what it means, why you’re using it, and what they should expect.

There are many ways to do this, but two of the best are including it as part of your documentation and via your mailing list (or other regular company communications). By doing so, you will help them to manage their expectations and not be surprised or alarmed as the version number changes and grows.

If you look around at the most significant proponents of semantic versioning, such as Ubuntu, Firefox, and Google Chrome, you’ll see that they have all published release schedules.

[caption id="attachment_6048" align="aligncenter" width="1024"]

Ubuntu release schedule[/caption]

The above screenshot from Ubuntu shows the name, codename, release date, and End of Life (EOL) date of each release. And you can see that it is broken down into current, future, and End of Life releases.

By providing this information, you:

• help bring users on the journey with you

• help them plan expenditure

• help them plan out when they have to set aside time and resources to upgrade to subsequent versions, whether major, minor, or patch.

In short, if you want users to work with you, be willing to work with them.

Like anything in life, if you want people to work with you, you have to be consistent and predictable. If you’re not, it makes it hard for your users to know what to expect -- and when.

If your release schedule releases a new major release every twelve months, do your best to stick to it. Don’t have one release published six months after the first, then one published twelve months after that, and another published two or three years later. Doing so breaks down the trust you’ve built with your users and negates the benefits of having a versioning system in the first place.

[caption id="attachment_6049" align="aligncenter" width="460"]

Counting to 10 with Microsoft[/caption]

An excellent example of this is the Microsoft Windows versioning system. I saw the image above a little while after Windows 10 was released.

I’d not given Microsoft’s style much thought before I saw it. However, it asks a fair question: how do you count to 10 at Microsoft?

While funny -- and perhaps Microsoft can get away with it -- there’s a serious side to it. With this kind of naming structure:

• How do you know if your installed version is the latest or whether it’s out of date?

• How do you know if you’re on the newest release?

This is especially important with the recent spate of ransomware, along with Spectre and Meltdown.

So do yourself a favor, use semantic versioning, and be consistent and predictable in your naming style. It may seem boring. However, the sizzle is in your product, not its version number!

With every new release, regardless of whether it’s major, minor, or a patch, communicate the changes to your users. Specifically, let them know the following four things:

1. What’s new

2. What’s been fixed

3. What’s been improved

4. What’s been deprecated

This can be done in several ways, but one of the best is by including it in your release notes. That begs the question: How? Well, there are many ways to write release notes, but ProdPad has some excellent advice. I’ve summarized it in the following quotes:

Good release notes are written to be read, clearly outlining what has been improved and how they benefit the users. Customers love that commitment to transparency -- it gives them a reason to trust you. We’ve been asked before whether we publish release notes -- probably because it’s a good indicator of whether we’re delivering what we promised on our roadmap.

Release notes are easier to digest when they’re divided into sections. Sections make for easier scanning for users. Writing clear, specific release notes help you open up a level of communication with your customers around the progress you’re making on your product.

Here’s a template from their blog, so that you can visualize the structure more easily:

[caption id="attachment_6050" align="aligncenter" width="600"]

Release notes template, copyright ProPad[/caption]

Let’s assume that you’ve centralized yourself around semantic versioning for versioning releases and that you’ve been following it for several months, if not several years. What are your users saying about it? Do they like the structure? Is it helping them? Have they complained about it? Are you moving too quickly for them (if only in their mind)?

This point isn’t specific to release versioning -- it applies to any endeavor where we have users or customers. We have to make sure that we talk to them on a regular basis and find out what they think.

If they’re happy with the system, if it works for them, it helps them do what they do that much better, then they’ll come on the journey with us and help us to improve it along the way.

So I encourage you, after you’ve invested the time and effort to implement a release versioning system, make sure you stay in touch with your users, gather feedback from them, and use it as much as possible. After all, your software is there to help them, not you.

That’s a key best practice for versioning software releases. Yes, there are any number of approaches, but semantic versioning is one of the most widely accepted and practiced ones in the software industry.

If you’re not already, I encourage you to look at your current approach and see:

1. if Semantic Versioning is an improvement,

2. how it may help provide greater clarity and transparency to your users, and

3. how it may help you communicate your goals to them that much easier.