11

Your package has a bug. Its API in some scenarios doesn’t follow the documentation and the intended behaviour. It has been that way since it was v1.0.0. You fix it to match the documentation. Should the next release be:

  1. Major / 2. Minor / 3. Patch?
Matt Harrison
  • 511
  • 2
    If you want a real-world example, the Rust release team allows breaking changes if they fix soundness bugs (i.e. violations of Rust's safety guarantees), without bumping the major version (Rust's major version is fixed at 1, and will stay there for the foreseeable future). – Sebastian Redl Mar 21 '18 at 09:49
  • 1
    Related: xkcd 1172. – Franklin Yu Aug 05 '18 at 01:50

3 Answers3

8

The absolute first thing you should do is ensure your tests are improved, so that at least one fails with the current code and passes when it is corrected to how it should have worked.

Next, if possible, canvas your users. Sometimes that's easy, eg if it's a paid-for licence, you potentially have contact details for every customer. If it's an OOS library though, you might have no idea who uses it. But if you can warn them, do so and act on their feedback as to whether it'll break their code or not.

If you can't canvas the users, you'll need to estimate the likelihood of it breaking someone's code. How obscure a bug is it? Just saying "it's been there since v1" doesn't give much of a clue to this. How many years ago did v1 get released? How many 10s, 100s, 100,000s of users do you have? If the discrepancy is disadvantageous to the user, then the likelihood of you breaking things is inversely proportional to no. of users * time. If though, the code functions in a way that is advantageous, then it'll be proportional (and I'd argue you should fix the docs in that case, not the code).

If it's very likely to break code in a big way, for many users, make it a major release. If it's really unlikely to break code, make it a patch. But also, take into account the likely reaction to this fix. Have hundreds of folk complained about it? If so, tend toward a major release just to promote the fact that it's now fixed. If no one has reported it, again lean toward a patch.

In conclusion you need to weigh up a bunch of factors specific to your situation and choose one. And remember, no matter which one you pick, someone will complain; that's just human nature :)

David Arno
  • 39,270
  • The main question is: how likely is it that some user relies on the "wrong" behaviour of the old releases? – Ralf Kleberhoff Mar 21 '18 at 19:04
  • 1
    This sounds more like "romantic versioning" than "semantic versioning". If it's a breaking change, it must be a major. If it's just a big fix without breaking change, it's a patch, not a major, no matter how much you love the fix. If it's a new feature or significant feature change, then it's a minor. semver is actually that simple. – Manuel Jun 24 '22 at 14:26
5

In the case you describe, there is a mismatch between the public API that is documented and its actual behaviour. As presented, to me bumping the patch version looks like the way to go.

But it is not necessarily that clear-cut.

There are a couple of questions in the SemVer FAQ that discuss the matter :

In short, context is key. What is the clearest way to put your point across to the public API consumers? How much of an impact would the fix be to them?

To reiterate, in my opinion bumping patch should be enough. That and properly documenting the bug. The use of SemVer does not mean public API consumers can safely upgrade from one version to another just by looking at the version number ; SemVer is about compatibility and upgrade effort, not safety. So they should check the documentation, including changelogs and known issues (that can be detected between the moment the version is release and they choose to upgrade) before doing the upgrade, and test to make sure the upgrade does not break their application before committing to it.

But ultimately, do what is less likely to alienate your public API consumers, which you know better than I do.

KevinLH
  • 399
  • 4
    One of the problems is that, like it or not, people will rely on the actual behavior of your software in addition to, or instead of, the documented behavior. There are tons of Python programs that rely on deterministic finalization, even though Guido van Rossum has always said that the reference counting GC in CPython is an internal private implementation detail that must not be relied upon. There are tons of Windows programs that rely on system directories being writable even though Microsoft has always expressly forbidden writing there, and they had to design and implement an entire – Jörg W Mittag Mar 21 '18 at 10:01
  • 3
    filesystem and registry virtualization system to finally make it possible to make system directories read-only in Vista, otherwise they would have broken hundreds of thousands of applications. Lots of Java applications rely on being able to generate JVM bytecode on the fly or use JVM reflection, even though there is nothing in the Java Language Specification that guarantees the existence of a JVM (and for example, on Android there is in fact no JVM). And so on and so forth. Every behavior of your program becomes a feature for someone. The designer of make realized after a couple of weeks … – Jörg W Mittag Mar 21 '18 at 10:04
  • 3
    … that having tabs and spaces both be significant whitespace and semantically different was a bad idea, but even by that time, even though at that time, he hadn't even distributed his prototype, there were already users outside of his organization, who had been given a copy from a colleague, who had received it from a friend, wo had received from an acquaintance … so he couldn't make such a breaking change, and 41 years later, we are still suffering for it. – Jörg W Mittag Mar 21 '18 at 10:08
0

semver only has three rules. and really it boils down to one.

  • If its a breaking change then its a major version.

Otherwise, you can argue about whether you are adding a feature or not and use minor or patch as you choose.

If you break the first rule, you break everyone who uses your library's dependency chains.

You force them to specific exact versions rather than 1.x

People will stop using your software.

Ewan
  • 75,506