SemVer: "Fixing mistakes" section

[stefanv]

Hi Jacob,

Thanks for writing up EffVer. I enjoyed attending your talk and meeting you at EuroSciPy!

I read the document more closely today, and one section made me pause: "Fixing mistakes".

Many libraries in the ecosystem set their dependencies as, e.g., ">= 0.5".
Now imagine a scenario where you include a potentially disruptive bugfix in a minor release. The moment you make the release, a bunch of dependent libraries scurry to fix their code. Because you "broke" the EffVer contract, it's more work for them than they intended, but they manage. Now, you go and revert the change and make a potentially breaking change to your library by re-introducing the previous behavior. This cause confusion among dependent libraries' users, and therefore among the dependent library developers.

What I'm trying to highlight here is that there are two categories of mistakes that you can make on a point release: (1) a change that is arguably suitable for a micro release, but ends up being more disruptive than expected 🤷‍♂️ and (2) a change that is unsuitable for a micro release, that got included by accident 🤦.

I'd argue that you should be extremely hesitant to employ the "Fixing your mistakes" approach, reserving it for emergencies such as (2) above. E.g., you may make an API change that accidentally changes the default value of a flag, resulting in silent changes to code output (woops!).

Anyway, long story short, I think it may be worth a warning on this section: don't do this unless you really need to, and only once you've thought whether reverting the change won't potentially cause more harm than keeping it. Most often, better to press on and get to the next meso release :)

[jacobtomlinson]

Thanks Stefan! It was great to meet you too. And thanks for putting thought into this, I'm very keen for this spec to be a collaborative effort.

The moment you make the release, a bunch of dependent libraries scurry to fix their code.

There's an assumption here that the majority of downstream projects will work around the accidental break immediately. In my experience it takes days or weeks for this to happen, way after the first issue has been reported about it. But I'd be interested to hear if this is not your experience.

When I wrote that section I was imagining that you would do this immediately after the first issue is raised about the problem, which is generally way before anyone has gone to the effort of implementing and releasing a workaround.

I think also I was only considering your (2) case and that this is something you would do in an emergency. In my experience this emergency happens on the order or monthly somewhere within the PyData community with someone accidentally releasing a break with an unsuitable version number.

I think it may be worth a warning on this section: don't do this unless you really need to, and only once you've thought whether reverting the change won't potentially cause more harm than keeping it.

I very much agree with this, and if the wording isn't clear in the post about this then I'm more than happy to change it.

Most often, better to press on and get to the next meso release :)

I agree less with this. Unless your broken release has been adopted and worked around by the majority of projects then it's better to fix the broken release. You definitely need to weigh up which approach will generate more effort, but for most projects undoing the break (within a day or two) is the path of least effort.

[stefanv]

I should also clarify that, nowadays, I am almost always thinking from the developer's perspective. There's a huge burden on (mostly volunteer) maintainers who have very little time already, hence the "moving forward" notion. Agreed that this may not be the path of least effort for the users!

[jacobtomlinson]

When it comes to libraries (which is where EffVer is likely to be most useful) aren't most users also developers/maintainers who also have users themselves?

[stefanv]

Depends on how deep you are in the dependency chain, I suppose. Skimage, eg, mostly has direct users, but NumPy has many libraries that depend on it. But, touché :)