Whenever you prepare to download a new version of some software that you use (anything from operating systems, to web browsers, to CMS platforms, to plug-ins, to apps for your smartphone or tablet), you’ll probably see a version number attached to it. But what does that number actually mean? Does it actually tell you anything about the upgrade that you are installing, or is it just part of a marketing campaign, such as Microsoft’s upcoming Windows10?
At Diagram, we want the version numbers of the software we create to provide some meaning, which is why we use Semantic Versioning. This helps us and our users understand more about each version of the software, with version numbers that let people know what is new, whether upgrading will cause any issues with existing functionality, and whether any development work will be needed to address these issues.
What Is Semantic Versioning?
The general idea behind Semantic Versioning is to put more meaning behind version numbers. Version numbers often don’t provide any information about whether moving from one major version to the next will cause any compatibility issues; Semantic Versioning attempts to solve this by indicating the extent of the changes within the version number.
In Semantic Versioning, version numbers are formatted as X.Y.Z, with X standing for Major Version, Y standing for Minor Version, and Z standing for Patch. But what exactly do each of these mean?
- Major Version – This indicates breaking changes, which will cause compatibility issues for any users who upgrade to that version of the software.
- Minor Version – This indicates that new changes or features were added, but the software is still backwards compatible, and programming changes will not be needed, except to implement any new features. Going from version 1.1 to 1.2 will only add new features, not cause any compatibility issues.
- Patch – This indicates that bug fixes were made. Upgrading from version 1.2.0 to 1.2.5 will not change any functionality other than fixing something that was not working correctly.
Why Use Semantic Versioning?
Semantic Versioning provides a good at-a-glace guide for developers, especially for anybody who works with public APIs that other people build tools with. If people can compare what version number they currently have with the latest release, they can understand whether they will need to resolve compatibility issues, if any new features have been added, or if any bug fixes were implemented. If they are upgrading to a new Major Version, they will need to address some major breaking changes, but upgrading to a new Minor Version will only require implementation of new features, and installing a new Patch will resolve bugs that currently exist.
At Diagram, we combine Semantic Versioning with Package Management to ensure that the software packages meet all the necessary compatibility requirements. NuGet, our package management system, will check the version numbers of modules that are being installed to ensure that installing a new version of software will not break compatibility. This allows us to offer a certain level of confidence that installing a new module or upgrade will not cause any major compatibility issues. This also helps avoid what developers call “dependency hell”, in which it can be difficult to determine which versions of different software modules are dependent on each other and how upgrading one piece of software can affect everything else.
Are There Any Downsides?
Some people complain that Semantic Versioning still does not offer enough detail. A higher Major Version or Minor Version number indicates that there are breaking changes or new features, but it does not say exactly what those changes or features are. Semantic Versioning is better for a quick guide that allows people to see whether they will need to address major compatibility issues or implement new features. Providing clear documentation on exactly what changes are being made in each release will help address this issue.
Another concern that has been raised is that if multiple breaking changes are introduced, major version numbers will go up in number quickly, making the prospect of upgrading from version 2.0 to version 5.0, for example, rather daunting. This can be addressed by offering a preview release rather than immediately introducing breaking changes. A preview release can be indicated by adding a hyphen and a term like “alpha” or “beta” at the end of the version number, such as 2.0.5-beta. This will allow for some more time for fixes to come in and address several changes at once in a new Major Version rather than introducing a new version number for each change.
Another possible pitfall of Semantic Versioning can occur when people use software in unanticipated ways. Sometimes, a bug may exist in the code, but some users have found a way for this bug to provide a certain functionality that they use. When a new Minor Version or Patch of the software is released that fixes this bug, it will end up being a breaking change for anybody who uses this bug. The Semantic Version number has no way to indicate that what is a Minor Version or Patch from the developer’s perspective is a Major Version change for some users. This can hopefully be avoided by providing documentation about what exactly is being changed in each version, but developers should be aware that while they do everything they can to indicate the effects of each update, the possibility of causing compatibility issues may still exist for some users.
Knowing Your Software
Some people disagree on the effectiveness of Semantic Versioning and whether it solves the issue of providing information about what is included in each version of a piece of software, but we believe that it is the best way to indicate how performing an upgrade will affect you. A Semantic Version number is not a true measure of the work needed to go from one version to another, since not all changes may affect everyone. It is more of a quick indicator of the changes that were made. Developers will need to review the release notes for each upgrade and manually check what will need to be updated or fixed. Doing so will ensure that any compatibility issues are addressed before they cause any functionality to break.
Do you have any questions for us about how to understand what exactly is being changed when you upgrade to a new version of software for your website? Do you need help addressing the compatibility issues that might arise when upgrading? Please contact us to speak with a Solutions Engineer, or feel free to leave a comment below.
