I am trying to plan a system which validates the compability of different components by comparing their semantic versioning number, especially the major release number (since it indicates API changes and backwards compability). I came across the following scenario where I could not find an exact answer:
Let's say the code is on version 2.3.5
and I add a new major API change, therefore updating the version to 3.0.0
. However, a few days after releasing I find that this change does not suit the users' needs, and I revert this change so that everything that was compatible with the versions 2.x.x
will be compatible again (note that I'm not doing a version control revert, but rather put the old version of the code back in a regular commit). Now I can't figure out if the new version should be 4.0.0
because I again did a major API change and the numbers should always be incremented, or, because it will be backwards compatible again, use 2.4.0
.
I see advantages and problems with both solutions. Are there ground rules or best practices for such cases?
Best Answer
Why you SHOULD go for a new major version according to semver?
Semver is a recommendation and not a regulation: ultimately, it's up to you to decide, as suggested by Bart. However, if you want to comply with semver, you MUST go to the next major version. First:
Second, because semver only defines version increase:
Why you SHOULD NOT go backwards in the version numbering
First of all, it is perfectly possible to create a maintenance release for a previous but sill maintained version. So if you have a branch
2.3.5
,2.4.0
and3.0.0
, you can very well create a bugfix2.3.6
, or a (backwards-compatible) feature version2.5.0
, as long as you do not create an overlap between the branches.However your scenario is different: going back for your main version creates inconsistencies . Suppose for example that you would go to
2.4.0
:latestmost advanced version would no longer be the largest number. This breaks a lot of assumptions about increasing version numbering. For example:What version would you see as the latest stable version in your wikipedia page? what would the customers of version
3.0.0
think of you and your reliability if they discover that they have a version after the latest stable version? what version would customer download if they are looking for the most advanced?If after
2.4.0
you would introduce a new major version, you would have to INCREMENT your major version. So it would be back again to3.0.0
. Would you rather go for3.1.0
(but perhaps your new version goes in a totally different direction ans is incompatible with the former version3.0.0
)? Or jump directly to version4.0.0
? In this case you would only have postponed the brutal version number increase.3.0.0
is deprecated?"API
3.0.0
is deprecated from version2.4.0
onwards"? really?Example: "if you use our package
7.1
you need his component3.0.0
; if you use our package7.2
you need his component2.4.0
" - really?Conclusion
I recommend to stick strictly to semver. Semver was not designed for marketing purpose nor for affinity. It was designed to facilitate the management of many dependencies between many components. The (consistent) number jump is really a minor inconvenience, compared to the assumptions a backwards numbering could break.