What is the goal of the PVP?

[michaelpj]

It's not clear to me what the design of the PVP is trying to do. The Rationale section is suggestive, but not quite clear to me. In particular, I can see two possible goals:

1. Keep packages compiling. The goal of the PVP is to identify which changes can cause downstream packages to no longer compile, and to signal those through appropriate version changes.
2. Keep packages working. The goal of the PVP is to identify which changes can cause downstream packages to no longer work in some broader sense, and to signal those through appropriate version changes.

The reason why it would be helpful to make this explicit is that it makes it easier to work out what is following the "spirit of the PVP" in cases where the text might not be fully clear or cover a corner case.

The reason this came up was the discussion about warnings for missing methods. Schematically, this is a situation where:

1. A user makes a change C to their library
2. C can make downstream code behave in a way we might consider "broken", but will not stop it from compiling. GHC will, however, emit a warning.
3. The proposal is to change the warning into an error.

Now, if our goal is goal 1, then this proposal changes what is a breaking change. Previously change C would not prevent downstream code from compiling, but now it will do. On the other hand, if our goal is goal 2, then arguably this was always a breaking change, since it can "break" downstream code.

But it's very hard to adjudicate such cases unless we know what the goal of the PVP is.

[phadej]

Well...

Deprecation. Deprecated entities (via a DEPRECATED pragma) SHOULD be counted as removed for the purposes of upgrading the API, because packages that use -Werror will be broken by the deprecation. In other words the new A.B SHOULD be greater than the previous A.B.

It's not far fetched to extrapolate that any new warning from -Wdefault group counts as a breaking change. That is IMHO a bit too strict.

With TemplateHaskell though (or dependent types), the "keep packages working" and "keep packages compiling" difference is quite blurred, so I'd suggest to opt-out for "keep packages working" understanding when you are unsure whether your change is breaking or not.

But then there is e.g. error messages. Is changing error messages in say aeson a breaking change? Some tests somewhere may fail, sure. Are anything truly broken? I doubt.

So the truth is probably somewhere in between. "Keep maintainers sane".

[sergv]

The PVP talks a lot about API versioning but doesn't really mention semantic side of changes, whether tests pass, etc. The PVP mandates a change in version when clients may get compilation error due to new changes, otherwise it doesn't require anything.

AFAIU the goal of the PVP is to keep thinks compiling when versions of dependencies are satisfied. Keeping things working is a much bigger goal.

[hasufell]

I don't think anyone knows, honestly. I don't believe PVP was designed properly. It's a versioning scheme and now we have to make decisions about user expectations, ecosystem and even the language (what is API). I believe it is ad-hoc.

[gbaz]

The PVP's origins are in the alternate policy which was a strawmanin the Eternal Compatibility article by Sven Moritz Hallberg in The Monad Reader in 2005: https://wiki.haskell.org/The_Monad.Reader/Issue2/EternalCompatibilityInTheory

In 2006, Bulat Ziganshin then proposed it be turned into a policy: https://mail.haskell.org/pipermail/haskell/2006-November/018762.html

Sven's motivation: "As a program module evolves, functions and other elements are added to, removed from, and changed in its interface. It is clear that programs importing the module (its dependants) will not be compatible with all versions. At least, each program is compatible with one version, the one the author originally used, and usually a few ones before and after that. But if a program is not continuously updated, with time, chances rise dramatically that one of its dependencies as installed on a given host system will be incompatible. Alas, the program cannot be used. This effect comprises a major source of bit rot."

Bulat's motivation: "library developer should just explicitly declare and obey some policy of incrementing library versions which will allow library user to select proper range of versions which are guaranteed to work with his code"

In both cases, the motivation was not quite specified enough to clearly read as goal 1 or goal 2 -- i.e. "guaranteed to work with" and "compatible with" can be taken to mean either goal. (Edit: and the PVP itself also speaks of compatibility, without having an a priori definition -- in a sense, it is the Haskell community's best effort at working out a common consensus on what compatibility itself means).

That said, to be clear, the PVP already specifies that any change to a typeclass is a breaking (major) change, which includes addition of new methods:

if any entity was removed, or the types of any entities or the definitions of datatypes or classes were changed, or orphan instances were added or any instances were removed, then the new A.B MUST be greater than the previous A.B

So I think in practice we have something more than "just compiles" but less than "will never make anything go wrong" and where precisely to draw that line is the job first of the pvp maintainers, and second of package authors themselves. Which is to say that the PVP specifies minimum criteria slightly more strict than option 1, and package maintainers may choose to go beyond these criteria in cases they feel appropriate.

I would also add that whatever the flaws (and I am happy to see so many people interested in resolving and improving them), in my experience and investigation, the PVP is better designed and more carefully thought through already than any alternative policy in any other ecosystem.

[hasufell]

and where precisely to draw that line is the job first of the pvp maintainers

It seems like the second time you postulate responsibilities for PVP maintainers.

Let me be very clear here: my opinion remains that this is not our job. And I will make no effort in developing those goals.

All proposals trying to extend PVP beyond the versioning scheme part will get a -1 vote from me.

[gbaz]

Let me be very clear here: my opinion remains that this is not our job. And I will make no effort in developing those goals.

I have been a maintainer on the PVP repo for a long time, as have other hackage trustees. Bodigrim asked if the CLC could take it over responsibility in consultation with us, and we acquiesced. If you don't want to be a part of that, feel free to walk away from this set of responsibilities. It makes no sense to have somebody as a maintainer who disagrees with the fundamental purpose and nature of the PVP, and the best thing for you to do in this situation would be to recuse yourself.

[hasufell]

Let me be very clear here: my opinion remains that this is not our job. And I will make no effort in developing those goals.

I have been a maintainer on the PVP repo for a long time, as have other hackage trustees. Bodigrim asked if the CLC could take it over responsibility in consultation with us, and we acquiesced. If you don't want to be a part of that, feel free to walk away from this set of responsibilities. It makes no sense to have somebody as a maintainer who disagrees with the fundamental purpose and nature of the PVP, and the best thing for you to do in this situation would be to recuse yourself.

I think that is incredibly rude (for the second time) and it seems to me you're trying to impose your understanding of PVP to the rest of the committee/maintainers.

If you've followed other committees like CLC or GHC SC you'll see that there are many instances of disagreements between committee members. Some CLC members might not believe that any addition to base is a good idea and vote -1 for all of them. That is democracy.

I have laid out my opinion in very great detail and provided reasoning.

I think it's fair to keep the existing wording around API breakage as a historical "best effort" description, but any addition to it will get us into more trouble about a language that is constantly evolving and not properly specified.

As to your suggestion: I will not recuse myself and I ask you to stop suggesting that.

[angerman]

@michaelpj I'm terribly sorry for having triggers this.
@gbaz for my understanding, can you outline what your view on the "fundamental purpose and nature of the PVP" is?
@hasufell maybe you can also outline what your view on the "fundamental purpose and nature of the PVP" is?

Maybe if there is a disagreement in understanding we can amend?

[hasufell]

@hasufell maybe you can also outline what your view on the "fundamental purpose and nature of the PVP" is?

It is a "Package Versioning Policy" as described on the front page.

It goes on specifying the rationale, which is

The goal of a versioning system is to inform clients of a package of changes to that package that might affect them, and to provide a way for clients to specify a particular version or range of versions of a dependency that they are compatible with.

In the later section it says

What is missing from this picture is 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. For some time there has been an informal policy in use in the Haskell community, but it became clear that we were running into trouble with incorrectly-specified dependencies and unbuildable packages, so this page is an attempt to formalize the policy.

Alright. This sounds like an attempt to specify what "API" means. It says here "is an attempt to formalize the policy". I've made clear in other threads that I believe this attempt has failed and I'd either:

1. freeze the state of this attempt and stop amending to it
2. remove it entirely (that has not gotten a majority vote)

As a committee member expected to vote on PVP matters I believe it's well within my right to adhere to 1 through my way of voting.

@gbaz has failed to convince me otherwise through demonstrating how we would:

• discuss and distill what is "API" in collaboration with GHC HQ and GHC SC
• maintain those properties in light of constant language evolution
• develop the required tools that are promised in the FAQ and actually fulfill the goal of helping library maintainers choose correct version numbers
• get to a state where PVP can be enforced on hackage
• explain who's going to fund this humongous project (I already lost all interest after these interactions)

Instead, all I see is "please leave the comittee if you don't agree with me". I'm sorry to disappoint. I'll need better arguments.

[simonpj]

Let's all stay polite here! We are all on the same side.

The PVP is not like the US constitution: a fixed document where we seek to divine the intentions of the authors. It is our living document. All we need do is to figure out what we want it to say.

As I understand it, if I change the semantics of an exported function (without changing its type), I should do a major version bump. For example, if I changed sort to sort backwards, I should do a major version bump. I suspect that there would be broad consensus on this point.

That sounds more like goal (2): keep clients working. Oddly, the actual words in the PVP spec do not mention changes in semantics/behaviour, but it is absolutely explicit in the diagram in the "decision tree" section, which says "Did the behavior of any exported functions change? Yes => major version bump."

Covering semantics is very much in the spirit of our agreed GHC base library proposal, where Section 3 describes the API that the CLC curates as covering semantics.

That said, it's clear that a promise to "keep clients working" is un-implementable. E.g. if I optimise a function so that it runs a lot faster, a client that depends on it running slowly will break. Fixing an outright bug is another example: it's a semantic change, and could conceivably break a client, but I think it's arguable that you should not feel obliged to make a major version bump every time you fix a bug.

So I don't think the PVP can ever be perfect. It can't tell you exactly what to do. But it can still be very helpful in setting general criteria, and laying down precise rules where (but only where) that is possible.

Concretely, my suggestion would be to add a numbered item in the "Version numbers" section, that covers changes in semantics.

[gbaz]

@gbaz for my understanding, can you outline what your view on the "fundamental purpose and nature of the PVP" is?

The purpose and nature of the PVP in my view was elaborated above. The PVP historically, in the citations I give, and also in the body of the text, both specifies the syntax of version numbers, and a best-effort at rules which delineate a minimum criteria by which some changes are considered "breaking" or "non-breaking" and thus would or would not require a major version number bump. As the text of the PVP rationale states, it provides "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."

The rub, which Simon observes, is that this cannot be anything but a "best effort" and lay down rules where possible.

I tend to agree that an explicit rule covering changes in semantics would be worthwhile, and this has been discussed at prior times, eg #41.

I think the guidance would have to be please use your head however. What we can accomplish by explicit rules firmly is (at best) only that packages keep compiling, but we can also encourage that changes that might otherwise be "morally breaking" (such as reversing sort direction) also trigger major version bumps.

[hasufell]

@simonpj

So I don't think the PVP can ever be perfect. It can't tell you exactly what to do. But it can still be very helpful in setting general criteria, and laying down precise rules where (but only where) that is possible.

This doesn't feel sufficient to me, unless the GHC SC wants to co-maintain PVP and oversee the "what is API?" part of it.

To re-iterate: I think this is significant effort. What is API in light of TypeApplications, LinearTypes, upcoming dependent types, etc. etc. GHC SC is free to innovate however they see fit and CLC now becomes the downstream consumer that needs to figure out how to define "API". That doesn't seem fair and I question that anyone has bandwidth for that particular part of the spec.

So I'm more interested in how you suggest this work is being done, continuously. A joint effort? A working group?

[simonpj]

To re-iterate: I think this is significant effort

What is "this"? My suggestion is as above: add an extra item covering semantics to the PVP. (I'd be happy with adding a more general "use your head" principle, with an attempt to explain what that means.)

I know that you don't think that is satisfactory, but it's (a bit) better than the status quo, isn't it? And it's very cheap to implement: excellent cost/benefit ratio.

Perhaps there is a much larger task that we could undertake together, but it'd have to compete with the other tasks that we are all working on, so we'd have to be convinced that the significant effort was going to have a good cost/benefit ratio.

[hasufell]

What is "this"?

Maintaining a satisfactory and up-to-date definition of what constitutes "API" in light of the latest GHC language.

My opinion is that piecemeal additions to the spec will not fix the underlying problem that Haskell users still are confused about how to manage their versions.

So I'm very skeptical unless someone makes a suggestion on how to maintain the definition of what constitutes API. This has not happened. As such I will keep my conservative stance.

Perhaps there is a much larger task that we could undertake together, but it'd have to compete with the other tasks that we are all working on, so we'd have to be convinced that the significant effort was going to have a good cost/benefit ratio.

Precisely. I'm also not sure the cost/benefit ratio is good enough to maintain the "API definition" part at all, which is why I've previously suggested to remove it completely, so someone else can maybe maintain it better.

[simonpj]

Precisely. I'm also not sure the cost/benefit ratio is good enough to maintain the "API definition" part at all, which is why I've previously suggested to remove it completely, so someone else can maybe maintain it better.

OK great.

• I (and I believe @gbaz) propose to add some words about semantics.
• You propose to remove some words. Can you make that more specific? What words exactly would you like to remove?
• Neither of us is proposing that we shoulud undertake the much larger task of "Maintaining a satisfactory and up-to-date definition of what constitutes "API" in light of the latest GHC language". (I'm not even quite sure what that means -- but it doesn't matter since neither of us is proposing to do it.)

That gives us two extant proposals, both relatively cheap to execute on. We could flesh them out with more specific language, and the the PVP curators can decide. Would that be helpful?