Clarify bumping policy for bug fixes

[andreasabel]

This question comes from:

• https://github.com/haskell/alex/issues/227

In this situation, position information generated by Alex < 3.2.7 had a bug that was fixed in 3.2.7. However, cabal had workarounds for the bug which broke after the bug was fixed.

The current PVP does not talk about behavioral changes of a definition, only about changing its type.

I would have thought a bugfix is a patch release (fourth digit bump). From the current example (workaround breaking) one could also argue for a major version bump for bug fixes that change the output of a function (rather than just making it more defined).

What is your take on this?

The PVP should be extended to mention bug fixes in the appropriate place.

[phadej]

Alex is not a library. PVP doesnt' apply directly. It's up to interpretation.

EDIT: In case of Cabal, I'd just regenerate the lexer, bump the minimum required version in tooling setup and call it a day.

EDIT: We had similar discussion with aeson. Do (exact spelling/formattin of) error messages it generates a part of public API. We agree that changing what's accepted / rejected is breaking change (people may rely on stuff being rejected, so relaxing parsers may introduce very subtly bugs, that's bad). But I don't remember whether we rely agreed on actual error messages (we just hold on doing them, in case of aeson there is a major version more or less always on the horizon).

[mixphix]

You are right that the PVP makes no mention of "changes to existing functions", only datatypes or classes. My gut tells me that Alex did the right thing here by bumping the minor version for this change instead of the major version. Perhaps we ought to change point 3 of the PVP, related to non-visible changes?

[phadej]

See https://github.com/haskell/pvp/issues/30

It's hard to formally specify which changes to function behaviors are breaking and which are not (see discussion about bug fixes in say npm ecosystem). Most (all?) criteria PVP lists affect the compile time, e.g. if you remove a data constructor, some programs may not compile anymore. Changing the behavior of the function OTOH doesn't affect compilation (in Haskell). The Cabal issue broke running result of a test, not compiling the test. It's same as error message changes discussed in #30.

I repeat, it's hard to formally objectively specify which changes in behavior are breaking and which aren't. Either extremes are valid, and everything in between.

[chshersh]

I always understood PVP as a policy that versions changes resulting in a compilation break. It's even written in the PVP description:

... a policy that tells the library developer how to set their version numbers, and tells a client how to write a dependency that means their package will not try to compile against an incompatible dependency

So, according to this policy, a package like aeson could suddenly start parsing YAML instead of JSON and it can be only a minor version bump if all types and names remain the same. This would be a huge breaking change for the users but PVP is fine with that.

In any case, when in doubt, always bump the major version. It's safer.