How to Number Versions of Software with Semantic Versioning
Most software is versioned according to a set of versioning standards known as Semantic Versioning.
The Semantic Versioning system, often abbreviated SemVer, uses a 3 number strategy to specify the evolution of software changes.
A specific version of software will be versioned like 1.0.0 where the first number represents the major version, the second is the minor version, and the third is the patch version.
Major, minor, and patch denote what type of changes a new version of software contains.
By agreeing on these versioning standards, developers can rely on dependencies and update them knowing whether or not they contain either breaking changes or backward-compatible changes.
How to Get the Next Version Number
Based on the numbering pattern, major.minor.patch, you can figure out what the next version number of your software should be based on the changes included in the new version.
Let's start with the most frequent version change, the patch number.
Patch Version
You should increment the Patch version when you make backward compatible bug fixes.
Patches indicate that your software has been fixed or improved in a way that shouldn't break existing integrations. As a result, it should generally be safe to pull newer versions of software on the same major and minor version but with a new, higher patch number.
If you fix a bug but in doing so have to rewrite other parts of the software or add additional features, this instead might warrant a bump to the Minor version number.
You shouldn't bump the Patch number in this case because the larger scope of changes now prevents others from safely updating the version they are on with as much confidence.
Minor Version
You should increment the Minor version when you add functionality in a way that is backward compatible.
Typically Minor version updates should be relatively safe to perform since they should not have blatant breaking changes. However, a Minor version change indicates that new functionality was indeed added or changed significantly and you should never assume a software update works without testing how it affects your system.
Also, the patch number is always reset to 0 after a minor version bump. After Rails 5.1.7 faced a Minor version bump to 5.2, the patch number got reset resulting in 5.2.0.
Major Version
You must increment the Major version if you introduce any breaking changes that are not backward compatible.
A major version change indicates that in order to update to this version of software, users will likely need to change how their software integrates or calls your new updated API. Major version upgrades require significantly more effort and careful planning since they will likely require users to include code changes of their own or to update other related dependencies.
Additionally, like with Minor version bumps, all versions are reset to 0 with a major version bump. After a breaking change on Rails 5.2.8, the resulting version number of the next release becomes 6.0.0.
Other Special Versions
Semantic Versioning allows for additional labels for versions of software that indicate pre-releases and other build metadata.
For example, before the release of Rails 7, there were a number of early builds as well as release candidates. You can take a look at the version history of Rails for examples like this:
7.0.0 - December 15, 2021
7.0.0.rc3 - December 14, 2021
7.0.0.rc2 - December 14, 2021
7.0.0.rc1 - December 06, 2021
7.0.0.alpha2 - September 15, 2021
7.0.0.alpha1 - September 15, 2021
Common Versioning Misconceptions
I'll admit at first when I saw version numbers all over software, I assumed you bumped the previous number up when you got to 9. I had no idea there was a standardized versioning spec known as Semantic Versioning.
But no, 1.0.9 does not become 1.1.0, it becomes 1.0.10.
Having a specification that explains when to bump each number takes the guesswork out of versioning new software updates.
And most importantly it lets other people who use your software know which updates are backward compatible bug fixes that are safe to pull and which contain breaking changes that need to be managed more carefully.
Version Numbers in Practice
Let's look at some versioning examples by diving into the version history of Rails, the most popular web development framework for the Ruby programming language.
2019
Rails 6.0.0 was released in August 2019.
Bugs were found but fixes were made such that all changes were backward compatible.
As a result, the first patch was released causing Rails to increment the patch number by 1. This became what we know as Rails 6.0.1 in November 2019.
2020
Most of 2020 was filled with backward compatible bug fixes so patch numbers continued to be incremented.
But in December 2020 Rails 6.1.0 was released. Meaning for over a year, Rails was patched numerous times but never significant enough to warrant a bump to the minor version.
2021
By January of 2021, only a month after the release of Rails 6.1.0, a patch was needed causing the patch number to increase, resulting in version 6.1.1.
By December 2021, we saw the release of Rails 7.0.0. This indicates breaking changes were made and that anyone wanting to update to this version would have to update a whole lot of dependencies on other code on their end.
Contrast that with the release of Rails 7.0.1 a month later, which was just a backward compatible patch. This means anyone could update without needing to really consider the patch notes. (Sort of kidding, it's always wise to see what you get and what changed in a new version of software)
Wrapping Up
Semantic Versioning has made software versioning and dependency management easier for all developers.
If you aren't following the SemVer spec, I highly recommend you try it out.
Just remember MAJOR.MINOR.PATCH and what changes warrant which part of the version to increase!