Clarify usage of “patch” component

[ffaf1]

The spec and the FAQ contain the expression “patch-level”.

It is confusing for some users,see this Discourse thread. The confusion is understandable: “patch-level” is nor defined nor mandated by the policy; PVP leaves any component beyond the third in the hands of the maintainer.

This PR makes rectifies this, using a more consistent and clearer vocabulary.

[hasufell]

I'm not sure we can retroactively change old spec versions?

[Bodigrim]

Target v1.1 please.

[hasufell]

I guess what we could do is: Mention in the spec itself that components after C are patch-level (e.g. after "A.B is known as the major version number, and C the minor version number").

I personally would like to move the "Special situations" and decision tree out of the spec and then not deal with this additional terminology at all.

[ffaf1]

Target v1.1 please.

Sure!

I guess what we could do is: Mention in the spec itself that components after C are patch-level […].

As now any component beyond C is optional, its semantic left to the maintainer. If we mention “patch-level”, we need to reword that bit of the spec and also define what patch-level means and applies to.

I personally would like […] not deal with this additional terminology at all.

Me too, hence this PR. The example works totally fine with A.B.C and without requiring new jargon. Adding new definitions is OK too, as long as they fix what happened in that Discourse thread (i.e. they are user friendly, clear and unambiguos).

[phadej]

If we mention “patch-level”, we need to reword that bit of the spec and also define what patch-level means and applies to.

We don't. PVP doesn't give any semantics to patch-level, but could have name for them. Note, the patch level is only mentioned in an example. That example could also say gets bump in a 4th component (as the bump is not required in any previous one)", but patch-level* is indeed a used name for 4th component, so going miles to avoid that name usage has no real benefit.

[ffaf1]

If we mention “patch-level”, we need to reword that bit of the spec and also define what patch-level means and applies to.

We don't. PVP doesn't give any semantics to patch-level, but could have name for them.

That would really be the worst of both worlds, wouldn’t it? Within a spec, using a term that already has some kind connotation, without stating precisely what it means.

This is not an inane speculation of mine, there is the Discourse thread: a user — a user with multiple years of professional Haskell experience — unsure what the spec refers to with “patch-level”. Compare with PVP referring to RFC2119 to define "MUST", "SHALL", etc. No space for amiguity there.

Same for it being “only mentioned in an example”. Example, yes, but still a spec document. No space for being sloppy in a spec. So I am partial to “define it or get rid of it”.

Let's see if we can gather more feedback from the other participants, this for sure is not urgent.

[phadej]

“define it or get rid of it”.

PVP doesn't give any semantics to patch level version numbers. It could explicitly say that these version digits don't give any semantics.

If that's "define" in your sense, than I agree. But giving any other semantics to patch level is changing PVP in a way I don't want it to be changed.

without stating precisely what it means.

I.e. PVP could say that patch version don't mean anything (and versions which differ only in patch digits should be compatible with each other). But in my humble opinion that is already clear from current spec. Someone has to be really clueless to imagine something else. It could be explained in FAQ, given few examples what these can be used for if really needed.

[phadej]

As now any component beyond C is optional, its semantic left to the maintainer.

Yes. That's exactly the point. PVP doesn't say which changes may or may not occur patch level. It says which changes MUST change major or minor version. And what doesn't need to change major or minor version could change patch version, or be a revision. Even is @hasufell doesn't want revisions mentioned in spec, they exist; cf. patch version exist, but IMO doesn't need to be mentioned in spec any more than revisions. (Note: what revisions can change is implementation defined, but it is possible to change things in metadata which would result a PVP violation: users needs to be aware of that and not do such revisions - an example is when packages re-exports definitions).

I don't understand how that is not clear from the current specification.

[hasufell]

That would really be the worst of both worlds, wouldn’t it? Within a spec, using a term that already has some kind connotation, without stating precisely what it means.

This is how specs are. They are often purposefully vague. Introducing terminology doesn't mean that we apply semantics to them. We can debate whether "patch-level" is the right terminology for something we don't want to apply semantics to.

An alternative is just calling them "optional version components". But that's even worse, since technically even B and C are optional. Then we could call them "undefined version components".

I think "patch-level" is fine. It doesn't say what a "patch" is.

---

The only alternative I see is that we start cleaning up the spec and move everything Haskell related to another document that is not part of the actual spec (basically everything after the "Version numbers" section). Then we can just define patch-level or whatever else in that non-spec document.

But people have been rather resistant to this idea.

[ffaf1]

I see there is little appetite for this proposal, hence I am closing it.