12

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.

Improve this question
5
  • 4
    I think the best you can do is bump 1.5.0 to 2.0.0, withdraw 1.5.0 so that it can no longer be downloaded, and notify your customers of the error. Commented Sep 19, 2022 at 3:25
  • 11
    Semver is concerned with API compatibility, period. "we didn't realise at the time that it would change the way our application is used so much" says nothing about API compatibility. It is a category error to think that extrinsic user behavior has any bearing on the representations you make about compatibility. Also, "we didn't realize at the time" is a clue that you should ignore this: we cannot rely on practices that require having future knowledge to properly decide current questions. Commented Sep 19, 2022 at 21:17
  • Call it "Hexium". Commented Sep 19, 2022 at 21:42
  • Advertise the new features, not the new version. Bumping the major number might scare some users off the migration. OTOH, I'd expect that writing blog posts about "Hey, see this new cool way to use our product" and ending them with "oh, by the way, you need to bump the version a little bit to get this cool stuff" might be more effective. Commented Sep 20, 2022 at 12:53
  • 1
    IMHO the versioning scheme is fine. What you want is to find a catchy name for that feature and publicize it. Commented Sep 20, 2022 at 18:21

4 Answers 4

Reset to default
34

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.

Improve this answer
4
  • 15
    "Conflating those two version numbers is going to cause confusion" ... "the Windows release with the Marketing Version Number 7 actually had the Technical Version Number 6.1." ... "Marketing Version Number 7 actually had the Technical Version Number 6.1. Windows 8 had 6.2, Windows 8.1 had 6.3." ...etc. Good thing that approach doesn't cause any confusion... Commented Sep 20, 2022 at 3:16
  • 7
    The version numbers don't have to be the same, but on the other hand, they probably should be, which makes this bad advice. You can certainly get away with it if you're Microsoft, but the asker is not likely to be representing Microsoft, and I wouldn't even recommend that Microsoft keep following this practice. Aside from that, I don't see how this answers the question, which is asking what to do when the technical version number was not incremented when it should have been. Commented Sep 20, 2022 at 7:35
  • 2
    Just because MS did this for Windows does not mean this is a generally good advice for everyone. Of course, it is also not a generally bad advice. Using a version number as "brand" it is a strategy which fits to certain organizations and products, and does not fit to others. Commented Sep 20, 2022 at 9:24
  • On the other hand, no-one confused 2000 for a version number, nor XP, nor Vista. The issue is with marketing version numbers, not marketing version names Commented Sep 21, 2022 at 10:19
7

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.

Improve this answer
5

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.

Improve this answer
1

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/

Improve this answer

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.