Best Practices for Versioning | TechRepublic

Software versioning provides a way to quickly identify the state of an API, package, or software product by assigning a unique name and/or a number. Versions help stakeholders keep track of changes to the code over time. There are a number different types of versioning schemes, the most popular being Semantic Versioning (SemVer), which was proposed by Tom Preston-Werner in 2013.

Regardless of which versioning scheme you employ to track your software changes, there are some principles and versioning best practices, developers can follow to make software releases go as smoothly as possible. In this programming tutorial, we will discuss a few of these.

Prior to reading our best practices to versioning guide, you may want to check out tutorial: What is Versioning?

Tell users which versioning scheme you are using

Most users know little to nothing about versioning schemes, so you should communicate to them which scheme you are using, what it means, and where they can find more information about it. There are several ways to go about this. For example, you can include it as part of your documentation or share the versioning details via your mailing list or other regular company communications. In any event, telling your users about your versioning scheme will help them to manage their expectations and not be surprised or alarmed whenever the version number changes and/or grows. By contrast, neglecting to inform users about your versioning scheme is likely to result in many unnecessary helpdesk calls – especially whenever a new version is released.

Maintain an open list of releases and changes

Think about some of the software you use regularly, and there is a very good chance that there is a published release schedule pertaining to it, most likely a web page on the company site. For example, here is Mozilla’s release schedule for the Firefox browser:

Image courtesy Mozilla.org

Clicking a version link brings you to a page with more information on that particular release, including the release date, what’s new, fixes, changes, developer information, and much more.

There are other pertinent details that you could share with your users, such as the the codename and planned End of Life (EOL) date of each release, if applicable. The latter is especially useful to users because it can help them plan expenditures and set aside time and resources to upgrade to subsequent versions.

Be consistent and predictable whenever possible

Nobody likes surprises, so the more users know what and when to expect, the better. That being said, if you can stick to a pre-defined release schedule, then do so. Moreover, if you do decide on a planned release schedule for your software, stick to it! You may want to think twice before putting out a release early just because you are ready ahead of schedule, or, more likely, decided to postpone some upgrades until a future release. Rather than be delighted, users may actually be annoyed, and start considering other product options. The reason is that ignoring your release schedule breaks down the trust you have built with your users and greatly undermines the benefits of having a versioning system in the first place.

Consistency and predictability also applies to your version names. While not an issue for semantic versioning, other naming schemes may become confusing over time. A good (bad?) example of this would be Microsoft, whose naming conventions for Windows seem to change at random. First, there was 1, 2 and 3, but then, suddenly without warning, they switched to the year for 95, 98, and 2000. Yet, for some reason, there was a release between 98 and 2000 named NT. After 2000, Microsoft mysteriously reverted back to proper names for XP and Vista, before finally going for numeric monikers again for 7, 8, and 10.

If developers remember to keep their version names boring and their products exciting, they will never go wrong!

Ask your users for their opinions

Once software developers have adopted a versioning scheme for their organization, how do they know that it is working optimally? Unless you ask your users, you can never know for sure. Do not just assume that because you are using semantic versioning and no one has complained that all is well. For reasons that may be unknown to you, semantic versioning may not be ideal for your product or users. There may be a better option that you have failed to consider.

Even if your software versioning scheme is the “correct” one, your users may have a lot to say about topics such as scheduling, finding release details, and probably a lot of other concerns that you never even considered. Since your software is designed with users in mind, why not let them have their say? Doing so can only help enhance user buy in and make them feel like they are part of the development process.

Anywhere programmers include release information is a good place to solicit opinions and questions from users, including the release list and changes pages as well as email communications. Also, do not forget about social media; it is the perfect forum to start a discussion about software releases.

Final thoughts on best practices for versioning

This programming tutorial highlighted just a few best practices for versioning that you can follow to make your releases go as smoothly as possible. In essence, it all comes down to communicating your goals with your users and providing them with as much clarity and transparency as possible. When in doubt, more information is always preferable to little or none.