Why choose Semantic Versioning (SemVer) for software
Context and problem statement
Since our core aim for the Seedcase Project is building software, we need some way of communicating changes made to our software whenever we release an update. Software versioning is an approach to communicating changes in a software whenever a new “version” or update is released that is widely used throughout the software industry, almost for as long as software as been built. But there are different ways to version software, so the question is:
Which style of software versioning do we use for our software projects?
Decision drivers
Like any software project, we need some way to communicate with ourselves, with contributors, with users who are developers, and with our non-technical users, what version of our software is installed. This is necessary to deal with bug reports, identifying issues that come up, and to communicate breaking changes, the addition of new features, or that bugs have been fixed. This type of communication and information is handled through the software version as well as the changelog that is based on the version.
Having versions also helps us in developing and deploying our software as we build and test things out.
Considered options
There are two major software versioning systems: semantic versioning, which bases the version on what was changed between releases, and calendar versioning, which bases the version on when the release was made. Broadly, each style has variations, which sometimes can be a combination of the two. We’ll compare the two most common, standardised systems:
SemVer
SemVar is a versioning system that uses a three-part version number: MAJOR.MINOR.PATCH. This system is widely used in the software industry and is well understood by developers. For instance, with a bug fix, PATCH is incremented by 1, going from 0.0.0 to 0.0.1. For MINOR, you increment by 1 when there is a new feature, so from 0.0.1 to 0.1.0. For MAJOR, you increment by 1 when there is a breaking change, so from 0.1.0 to 1.0.0.
Benefits
- This is the most widely used versioning system in the software industry, so it’s familiar to most people in the industry.
- It conveys information about changes well, since it’s clear from the numbering what has changed between versions
- It has a large number of tools and packages that support it, combine well with it, or integrate well into development workflows around it. For instance, tools like:
- Conventional Changelog to automatically generate changelogs based on the commit messages that use the Conventional Commits format.
- Python Semantic Release to automatically increment the version number based on the changes made and create a release based on changes to the version.
Drawbacks
- It can be very difficult to determine when something is a major, minor, or patch change. Sometimes it is perfectly clear, but often, a change is hard to place in these three categories.
- It can be difficult to determine what constitutes a breaking change.
- More difficult (but not impossible) to automate, since it can involve a large amount of human judgement.
CalVer
CalVer is a system that is based on dates. Unlike SemVer, there are more variations available to use, for instance, YYYY.MM or YY.MM. Also unlike SemVer, there are more often variations that combine features of SemVer and CalVer, such as YYYY.MINOR.PATCH.
Benefits
- Very easy to use and understand, as it is based on dates. Whatever date the software is released on is the version number.
- Works very well for some software projects, especially those with very regular releases. For instance, the most popular Linux distribution, Ubuntu, uses a form of CalVer, that increment every 6 months.
Drawbacks
- It doesn’t contain any information on what was changed between versions.
- Breaking changes are not communicated in the version number.
- There are substantially fewer tools and packages to help automate release and development workflows compared to SemVer.
- Doesn’t work as well for some software projects, especially those that are not released on a regular basis.
Decision outcome
We decided to use Semantic Versioning (SemVar) for versioning our software. While it can be more difficult to implement as it may require some human judgement to decide on which version to increment based on the changes made, because it is so widely used, the availability of tools that support it or exclusively depend on it is very large. It will ultimately make it easier for us during development because we can make use of those existing tools to handle tasks like version release and changelog generation for us.
Consequences
One of the biggest consequences of using SemVer is that it does take a bit of effort to implement the tools that will eventually automate many of our tasks for us.
There will also be some variation in how individual team members and contributors label changes, since there is some level of human judgement on categorising changes into the correct version number. This will involve some learning for the team.