Give guidance about patch releases?

[tfausak]

Currently the PVP does not talk about patch releases at all. It only specifies A.B.C version numbers, which include two major versions for breaking changes and one minor version for non-breaking additions. For bug fixes that don't introduce anything new, what is the recommended course of action? I typically see packages either increment C or add a new version component D and increment that for bug fixes.

[phadej]

I agree that this should be clarified, but maybe first as the FAQ item, and maybe later "promoted" to the spec. I can make a PR early January, if this is ok course of action.

@hvr is PVP change process documented somewhere ATM? (IIRC CLC has to accept the change at the end, so I'd start with a FAQ first)

[23Skidoo]

Yep, it's not 100% clear to me whether "change in the behaviour of any exported function" encompasses bug fixes. Case in point: haskell/cabal#4764.

[hvr]

@23Skidoo it's admittedly a bit of an inconvenient aspect of semantic versioning; if the bug-fix is backward compatible, i.e. doesn't affect the official API, then a patch-level increment is fine (however, there's rather few things that fall into this category; mostly haddock fixes, warning fixes, fixes in non-public or "internal" APIs, compatibility code fixes, and stuff like that). That's also why MIN_VERSION_... macros are blind to anything below major/minor versions, because they're not supposed to have any affect on the official API surface.

However, the change/fix you point out in Cabal unfortunately is clearly a semantic change of the behavior of an existing function. So if you're strict about the intention of the versioning contract, it would demand a major version increment (because it has the potential to break consumers that didn't expect foreign libs to be included in allBuildInfo), and even if you're super pragmatic about it, at the very least a minor version increment is needed so that consumers can at least make use of MIN_VERSION_Cabal to discriminate against such a change.

[23Skidoo]

@hvr Thanks. I was already going to increment the minor version because a new public function was added.

[domenkozar]

Another case in point: https://github.com/haskell-servant/servant/pull/1128/files#diff-7fedec2746833fb79889ad2222571a3dR553

PVP actually dictates major bump for a runtime error fix, which is now is either correct behavior (or it fails at compile time).