Benefits of Versioning your Software

I think versioning your software product releases is always a good idea. With all software products, whether we’re talking about websites, API’s, multi-platform mobile apps, software programming to embed into a specialized hardware device, or whatever, versioning your releases of each product can provide some benefits to you, your team, and sometimes the product’s users too.

One Suggested Approach

There are several approaches you can take for versioning releases, but for the purposes of this discussion, let’s stick with semantic versioning for its simple efficacy and wide usage within the software development industry. Semantic versioning is basically summed up as “Major.Minor.Patch” where a Major number increase tends to involve the initial production-ready release (1.0), breaking changes, or a very major feature or rewrite, a Minor number increase tends to involve backward-compatible feature expansion, and a Patch number increase tends to involve fixing at least one issue in a backward-compatible way. When increasing a Major value, the Minor and Patch values reset to 0, and when increasing a Minor value, the Patch value resets to 0. See here[https://www.cloudbees.com/blog/best-practices-when-versioning-a-release/] for best practices when versioning a release, and here[https://semver.org/] for further details about what semantic versioning is. At AWH, we use Jira with Releases, and we populate Fixed Version fields (a choice between created release versions) on specific issue types (prior to starting their implementation), and we automate Bug and Story transitions for the ones fixed in the version from “Dev Complete” to “Ready For Testing” upon releasing a Jira Release to the Test environment (those eventually then go into “Testing,” then after the related tests pass (or related Bugs get found/fixed/deployed/tested and then pass), to “Done”). For people who need to know what has been newly introduced in a deployment or release version, the ideal solution would allow them to access and refer back to that info in release documentation whenever necessary, to preview release information prior to its release, and also to look into the contents of prior versions when desired; all of those things can be done with this suggested approach.

Why Bother with Versioning?

The short answer is clarity in release communications across every perspective. A recurring difficulty I’ve seen in software deployment processes on small projects, and especially regarding software testing, is uncertainty about what new features or fixes are expected to have been included in the deployment to the environment about to be tested. This problem comes down to a lack of communication of the necessary information. When release information is unclearly or insufficiently communicated (this could break in a number of ways — thoroughness, timing if plans change, wrong or incomplete audience, forgetting to send a communication, having a different person than normal deploying because the regular person is on vacation or busy and this person handles release communication differently, etc.), the expectations for the release can be hazy or obscure or entirely missing, and the info is usually unavailable until the moment of that communication. However, when the set of included changes in a deployment are well documented and communicated from the time planning occurs through the implementation and then release, by associating tasks with a release version number where all such linked issues and additional details are accessible from a release page, the expectations for included features are clear and everyone is in the loop and happy. Let’s call that clarity “release feature transparency,” which is essentially a measure of the quality of the communication of info regarding the actual set of included changes/features in any given version of a software product (where the version could be used as a label for a deployment, environment, or instance).

What benefits can be realized using software release version numbers and the suggested approach?

Release feature transparency for anyone with visibility into the release documentation. This could include testers, developers, project managers, and sometimes the client or product stakeholders.

A preview of contents of an upcoming release according to current plans — this is especially beneficial for testers to prepare test cases but could also be useful for any desired preparations in other roles, even potentially expanding into customer service and marketing.

You have a narrowed scope of code commits to search through when developers look for possible causes for an issue reported as found in a specific version.

Clear and easy visibility into each environment’s active version, displayed in the product, and (via the release documentation) what features should exist in that environment.

An always accessible label for the exact codebase to deploy (or redeploy so you have something to fall back to) for a release, assuming you use Git and you tag the commit representing the release with the version number; doing that makes it much easier to set up automation for some types of products for lower environment deployments that are triggered by the creation of such a tag.

Insight into project progress via a list of releases (for project managers or other product stakeholders), starting at a high-level view of releases, with the ability to drill down into details in each release.

Quick diagnosing in any specific environment of what should be expected or not regarding recent feature additions, including which environments have which product version — one just needs to match the displayed version in any environment to the corresponding release documentation; this also allows one to verify the success of a deployment.

For developers of software products that utilize yours who need to manually upgrade their version usage, those developers will be able to know, at a glance, which version upgrades will need special attention for breaking changes: only the major version increases (after 1.0); additionally, they’ll be able to tell by the numbering and available versions how many versions they are behind the current one.

Due to the always increasing version numbers, it is perfectly clear which version represents the latest, both overall and under a particular major release number (2.1.0 is a more up-to-date version than 1.18.0 or 1.4.3 or 0.26.1 or any of the versions between those).

Quite often, programmers are developing features in one branch of the source code simultaneously to testers validating expected functionality in one or more deployed environments, so without documentation, it’s more difficult for testers and/or users to know what features they should expect to be available in their current version and what features should not be available. The combination of applying software versioning in code (Git tags and in project code) and in task tracking, and associating features/tasks to the version number they get completed in (inaccessible documentation that could be mostly generated by your task tracking system) and making the version number visible within the software product, solves this problem, and others too. With this setup, after a deployment is made and a tester is made aware (could be notified by an automated trigger on a release or a status change on tasks or a simple message to a group like “Product ABC version 1.4.0 is deployed to the Test environment” or even just “Deployed” could be sufficient in the right context), a tester could see the version number on the product, see and refer to the release documentation listing the newly completed features and fixes associated with the version number, and test with confidence, assured of what is supposed to be included. Not only that, but anyone on the team can do the same. Also, with that approach and information available prior to the deployment, your testers can prepare test cases in advance, because they have the knowledge of what is going to be released next. If your version number is visible in the product, then anyone, even a user in Production can include the extremely helpful specific product version number in which they first encountered any problem they report.

Stay Consistent

As mentioned in the best practices article linked earlier, it’s important to stick with your version conventions. Consumers of your product will appreciate the consistency and clarity of sticking with one versioning approach throughout the life of the product. You may decide that semantic versioning isn’t your preference, and you’d prefer something with a build date and timestamp in it, or something with a word in a specific category that starts with increasing letters of the alphabet (like Android operating system names, which they eventually switched away from), or something else that might be entirely novel. Whatever you choose, plan on sticking with it through the life of the product, and design your choice so that it can work for that long. It is quite disruptive to the expectations and causes negative implications for users and other tools that depend on your product when a version number design shifts (or shifts multiple times — like with version names for Microsoft Windows).

If you vary your versioning drastically, you’re going to create some confusion all around. For example, the expectations about the version compared to the previous one will be off, there will be confusion about what boundaries a version does or doesn’t cross, and the meaningfulness of the versioning will be reduced drastically. Can I execute programs in Windows XP that I currently use in 2000? How many major versions behind is 2000 from 10? If I upgrade now, when might the next version come out? In two years? In two months? Consistency in version naming and at least approximate regularity in release schedule are both key factors in molding and meeting the expectations of those who rely on your software product.

Start applying versioning to your software products today and reap some of these benefits for your team, clients, and users. If you already use versioning, then you’ve seen some of these benefits in action. Maybe you could also consider a few variations in documentation or automation to improve your processes even further. Happy versioning!