Switching to semantic versioning from simple version numbers

Question

There's a software library / application / framework which currently uses "simple version numbers". So it's currently at (say) version 135 and releases are made in irregular intervals whenever "there's enough for a new release". The next release would be 136 in this scheme.

I want to switch this to use semantic versioning (version numbers and release behavior, of course).

What version should I use for the "first" semantic version?

That is, should the next release be 135.1.0 ... or 136.0.0. Or 1.0.0? What is the "correct" approach and which approach breaks the least number of version comparison algorithms?

Answer 1

I suggest conceptually re-interpereting the existing version numbers 1,2,3,...,134,135 as semver versions 1.0.0, 2.0.0, 3.0.0... 134.0.0, 135.0.0

Then just follow the rules of semver to decide how to number the next release - 136.0.0 if it may have a breaking change, 135.1.0 if it may contain new functionality, or 135.0.1 if it has no changes other than bug fixes.

Answer 2

Choosing which number to start is the easiest part of switching to semantic versioning. Maintaining a semantic version number is a significant investment. Simple versioning makes no promises that any upgrade won't introduce breaking changes, semantic versioning does imply that minor version can be upgraded without breaking changes. This means you must spend the effort to determine which new features are eligible for a minor release, this is not always straightforward. You may also have to start support multiple versions of code for brief periods, if you release 2.0 and a major security vulnerability is found that affects 1.5 as well are you going to patch both versions. If you aren't going to support older versions, then there isn't much point in switching since the only upgrade path is the next major version. What happens when you upgrade your own dependencies, is that just a minor version? Is semantic versioning even going to be beneficial to you, in two years will your version go from x.0.0 to x+5.0.0 or x.20.0? If you only end up incrementing a single part of the version number it's not different from simple versioning anyway.

There is a cost to having a semantic version, and you really need to make sure you are actually benefiting enough to justify that cost. If you feel that you are, just starting and 136.0.0 is the easiest solution, if you want to reset to 1.0.0 then you should tweak the name or something to help clarify the change.

Answer 3

SemVer is defined for public APIs only. If your development does not define such an API, you'll first have to interpret SemVer to clarify its use for software without public API or other forms of content.

You should not restart your versioning from 1.0.0:

• for practical reasons, in order to avoid the risk of any confusion with version 1, 10 and 100.
• for formal reasons, because SemVer-clause 4 reserves major version 0 for the development stage with unstable and public API, and SemVer-clause 5 reserves version 1.0.0 for the initial definition of the stable public API. In view of your wording, I understand that the next version would not be the first official version that defines the API. So 1.0.0 would not be compliant.

The rigorous approach of reverse analyse each of your past releases to determine their real SemVer version is to be avoided. For practical reasons: It would be very time consuming and the story of why you switched from version 136 to version 12.4.5 would not be very interesting to hear.

The most prudent would be to start at 136.0.0. It's a fresh start. Everybody will understand, and the version history goes upwards. I'd recommend this one if your product is already quite old very mature (e.g. monthly release in average) or if you don't want to answer unnecessary questions from your customers.

An alternative, if your product is still quite new (e.g. weekly release in average in the past). Could be so start at version 2.0.0. This could be justified by stating that you adopt a dotted versioning scheme and that you consider the old version as 1.3.5 and the next major version (after all you change the versioning logic!) is 2.0.0.

Now, if you're in commercial software, a pragmatic and often-used market oriented approach would be to take 2 major versions ahead of your biggest competitor. Your customers will understand that your product is the most advanced one. But as a software engineer, don't try to find an explanation: let the marketing department chose the most convincing narrative ;-) /* Needless to say: I cannot objectively recommend this last approach */