Return to semver

[wbt]

This discussion is a continuation of this one. In short, Truffle and related projects (like web3.js) used to release breaking changes on patch-level releases often, then got away from that practice with better adherence to semver, and Truffle has more recently returned to breaking changes in patch-level releases. This is a discussion aiming to try and fix that again, especially to cut down on the frequency of breaking changes on patch-level releases.

As I hope you understand (in the abstract), there's often a judgment call.

I do understand this isn't easy, and I won't even claim that I always get this right. (Debugging issues that suddenly show up through hours of eliminating other possible suspects and finding out it's Truffle releasing a breaking change on a patch-level release also isn't easy, so I do think it's worth some discussion to try to get this right.)

When I'm making the call, I first look at the changes and for each, I ask if this changes anything about a published interface. If so, I try to think of as many ways as I can in which people might be using that interface currently which would be incompatible with the new version. Moving the location of the distributed code (the immediate prompt for this discussion) seems to pretty clearly fall into this category. Removing an exported function or altering the signature of an exported function in a way that changes the types of parameters to be at all incompatible with any possible use of the old version also seems to be in that category. Changing the name of an exported function does too. This part of the version numbering process is the most important and requires the most creative thinking about how people might possibly be interacting with the code.

If I can come up with a single example of how someone might possibly be using the code now that would be broken with the new release, it gets a major version bump and a release note about just what that change is. Changing a major version number in either direction might require updates in calling code, and the documentation should make it as easy as possible for a reader who knows their own code to determine if their code would require any changes (and if so, what changes). If a prior version had an issue requiring a workaround and the new version breaks that workaround, that's a breaking change. (Here is a clear example from a Truffle-adjacent project).

If there's not going to be a major-version bump, I then ask if the new code allows someone to do something they couldn't have reasonably expected to be able to do before, justifying a feature-level bump: no existing code should break, but users of the new feature would not be able to use a version with a lower feature-version number without code modifications to remove that.

Patch-level releases should only be for occasions like internal reorganization, efficiency improvements, and other things that don't require any changes to how people interact with the code being published, even if they're interacting with it very creatively.

[gnidan]

Sorry for the delay responding here... I've scheduled a team discussion as part of our regular alignment planning sessions; we've just been behind on other, earlier-added topics. I haven't forgotten about this... really I haven't even stopped thinking about it. Thank you for bearing with me.

[gnidan]

For full transparency, our next team-wide alignment session is 2022-09-13. I wish it were sooner than that, but various factors make that impossible :/. I'll see what I can do, but if nothing else, I will ensure we discuss this semver concern during that call as a top priority.

[wbt]

Node itself just did this and it's quite frustrating from a developer perspective. They added the "experimental" warning log after the breaking change rather than before, and then locked out discussion with a claim otherwise, which adds more frustration.