Guidance on rectifying a minor bump that should have been a major bump

Question

We have product X which has the following semver versions: 1.0.0, 1.1.0, 1.2.0, ..., 1.10.0.

In version 1.5.0, we introduced a feature which changes the way the application is consumed in a big way. Eventhough the change is backwards compatible (which means a minor bump would be appropriate), we didn't realise at the time that it would change the way our application is used so much. So in hindsight, we should have done a major bump to 2.0.0.

Is there any guidance around how to handle this situation? Should we just release a 2.0.0 now and deprecate all versions before 1.5.0 eventhough they're perfectly fine and supported? Or should we "republish" 1.5.0 as a 2.0.0 and then "replay" the 1.0 releases to 2.1.0, 2.2.0, 2.3.0, etc and carry on like that.

My overall goal is that I want consumers to know that if they are on a version that is before 1.5.0, they really should look at upgrading, because "1.5.0" of the product introduced a big backwards-compatible change.

Answer 1

You are mixing two different version numbers here:

• The "Technical Version Number" and
• The "Marketing Version Number".

Don't do that.

Conflating those two version numbers is going to cause confusion.

If you want to signal to your users a cool new feature, increase the Marketing Version Number. Leave the Technical Version Number to proper Semantic Versioning, i.e. only to signal changes to the public API.

Take Microsoft Windows NT, for example. Microsoft Windows 2000 to Microsoft Windows XP was a major user-visible change with a significantly different user experience, but from an API perspective, it was fully backwards-compatible, so the Technical Version Number only got bumped from 5.0 to 5.1. Windows Vista had much more strict security rules which broke quite a number of applications, so it had Technical Version Number 6.0. Windows 7 was only a minor update to Windows Vista, and so the Windows release with the Marketing Version Number 7 actually had the Technical Version Number 6.1. Windows 8 had 6.2, Windows 8.1 had 6.3. From Windows 10 on, Microsoft is using a rolling release model, so all versions of both Windows 10 and Windows Server have 10.0. Even Windows 11 still has the Technical Version Number 10.0.

So, as you can see, the Technical Version Number used to signal backwards (in)compatibility and the Marketing Version Number used to signal "buy this upgrade, it is shiny!!!" don't have to be the same.

Answer 2

Given that the API is still backwards compatible, strict adherence to Semantic Versioning 2.0.0 would suggest that you are OK with just bump the minor version.

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes

MINOR version when you add functionality in a backwards compatible manner

PATCH version when you make backwards compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format

But, it sounds like from above, that the change was big enough that even-though it is backwards compatible from an API point of view, semantically you want the users to know about the change. The above is similar to the following guidance:

What if I inadvertently alter the public API in a way that is not compliant with the version number change (i.e. the code incorrectly introduces a major breaking change in a patch release)?

Use your best judgment. If you have a huge audience that will be drastically impacted by changing the behavior back to what the public API intended, then it may be best to perform a major version release, even though the fix could strictly be considered a patch release. Remember, Semantic Versioning is all about conveying meaning by how the version number changes. If these changes are important to your users, use the version number to inform them.

Those last two sentences are at the heart of your question ...

Remember, Semantic Versioning is all about conveying meaning by how the version number changes. If these changes are important to your users, use the version number to inform them.

So if the API change is different enough, then OK to perform 2.0.0 and deprecate the earlier versions.

Answer 3

It sounds like you are considering not to use SemVer rules literally and exclusively here, but also to take care of advertising aspects, at least at the MAJOR level. Opposed to what the most upvoted answer says, this is not necessarily problematic, as long as you don't have a huge marketing department for your API which is working separately from the development team.

Technically, it is ok to increase the MAJOR version number sometimes even when formally not necessary - increasing the major version when a change is backwards compatible does not lead to hard technical issues, when you don't do this too often. But it shows that this is a decision to be made under advertising / marketing aspects.

Ask yourself, what is more important for you to signal to your clients:

• the new version is a huge improvement and will change they whole way of working with the API? Then bump to V2.0.0.

• the new version still allows easy transition from 1.4.x? Then stick to 1.5.0

In case one has contractual issues to obey, for instance, how long a vendor will support and maintain older major versions after a new major version was published, then one needs to take them into account as well.

So in short, for the former cases, SemVer rules alone won't help - one may has to think about perceiption by the customers, and sometimes about the contents of the contracts.

Answer 4

SemVer is for APIs, not products in general. It has a technical definition, and a major version increase is correct if and only if the API has had a breaking change. It is not meant to signal general product changes or improvements. Many orgs have a cargo cultish adherence to SemVer, but there are plenty of other reasonable versioning schemes both for things with and without APIs, e.g. https://calver.org/