Best Practices When Versioning a Release

In the world of software management, there exists a dreaded place called "dependency hell". The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair.

When a new release of software introduce to the user, 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.

Well, consider this scenario: A user purchased and installed version 7 of your software some months ago, and recently you released a new, major version. However, instead of naming it version 8, you name it 8.1. Even worse, you gave it a human name or skipped several versions, say to version 15.

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 a new version 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!

I want to show you an industry best practice; it’s called semantic versioning.

How Does Semantic Versioning Work?

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

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

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

Semantic Versioning Specification (SemVer)

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.
2. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.
3. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
5. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.
6. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backward-compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.
7. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when a minor version is incremented.
8. Major version X (X.y.z | X > 0) MUST be incremented if any backward-incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor version MUST be reset to 0 when a major version is incremented.
9. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
10. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
11. Precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into a major, minor, patch, and pre-release identifiers in that order (Build metadata does not figure into precedence). Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version. Example: 1.0.0-alpha < 1.0.0. Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: identifiers consisting of only digits are compared numerically and identifiers with letters or hyphens are compared lexically in ASCII sort order. Numeric identifiers always have lower precedence than non-numeric identifiers. A larger set of pre-release fields has higher precedence than a smaller set if all of the preceding identifiers are equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Five Tips for Implementing Semantic Versioning

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.

1. Communicate clearly to your users

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.

2. Have an open release schedule (that changes gradually)

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.

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.

3. Be consistent and predictable

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.

4. Communicate changes regularly and transparently

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.

5. Get user feedback

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.

In Conclusion

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