Wording about A.B.C number

[phadej]

A package version number SHOULD have the form A.B.C, and MAY
optionally have any number of additional components, for example 2.1.0.4
(in this case, A=2, B=1, C=0). This policy defines the meaning of
the first three components A-C, the other components can be used in
any way the package maintainer sees fit.

This should mention that version could be e.g. just 1, but than it means that following components are 0, for example example-package-1. Probably also that one MUST NOT release example-package-1 and example-package-1.0 (Does hackage-server enforce this?)

[bergmark]

What is the reason for MUST NOT release v1 and v1.0? It's confusing but I don't think there would be any problems since v1.0 > v1. Rather, a problem is with A or A.B releases by themselves since they cannot be matched by the MIN_VERSION_pkg(a,b,c) macro.

[phadej]

@bergmark I guess, when other bullet points in policy talk about

A.B MAY remain the same but the new C MUST be greater than the old C

but what's the old C when it's absent. If it's treated as -1 (which can be implemented for MIN_VERSION_pkg macro, then I don't see a problem. Yet I would still advice against it, i.e. RECOMMENDED using full versions (e.g. 1.0.0.0) or treating missing digits as 0.

[tfausak]

I had always assumed PVP versions MUST have 4 parts, A.B.C.D. I was surprised to find packages with releases like 4.13.2.1, 4.14, and 4.15.1. It makes it hard to set bounds since the correct lower bound is >= A.B.C, but 4.14.0 is greater than 4.14 so >= 4.14.0 won't include 4.14.

[bergmark]

It makes it hard to set bounds since the correct lower bound is >= A.B.C, but 4.14.0 is greater than 4.14 so >= 4.14.0 won't include 4.14.

The only rule you need to follow to avoid this issue this is to never have a >= x.0 lower bound, always use just >= x. So I wouldn't say hard :) but it's unintuitive and error prone.

[hvr]

@bergmark btw, I've been meaning to have cabal check report a few version-range linter warnings; there's a couple of common mistakes ppl do on hackage like using > instead of >=, or <= instead of < (as outer bounds);

[tfausak]

I know this has been fixed in Hackage, but according to the PVP spec it's allowed to add features between an A.B release and an A.B.0 release. So the >= A.B and >= A.B.0 bounds aren't the same.

If the spec changed to match Hackage, that would be fine.

[m-renaud]

Super incredibly late to the party here 😜

@tfausak

according to the PVP spec it's allowed to add features between an A.B release and an A.B.0 release

How so? Someone correct me if I'm wrong, but if I have a release A.B, there's no way for me to release a new version (even a "patch") without it being at least version A.B.0.1. In which case, if you know your package works with foo-A.B then it should be safe to set the bounds foo >=A.B && <A.(B+1). Also, in essences this means that by releasing a package foo-1 there's no way to release a "patch" of this version without creating a new major version (see my paragraph below).

Also, I've started looking into the cabal check changes that @hvr mentions above.

Going back to the original issue, I do agree that having a single component version number is confusing. As a concrete example, say I have the package foo-1, this can be thought of as foo-1.0 but according to Data.Version it isn't. Here's my reasoning: the PVP states that the first two components are major versions, and since 1 < 1.0 and the latter has a new version component, I would consider foo-1.0 a new major release of the package foo. I think this issue really only arises at the major version level because major versions have the inherent semantics of "breaking things". In almost all cases the later version components don't matter for constraints since they shouldn't break the public API.

State in terms of equations: the PVP is worded as if foo-1 == foo-1.0 (aka ver 1 == ver 1.0), but Version [1] < Version [1, 0] which is a contradiction.

It's great that Hackage will no longer accept new packages that only add a trailing 0, but I think it would be useful if Version [1] == Version [1,0]. Either that, or it should be clarified that to properly set bounds for a dependency on foo-1 you should set foo >=1 && <1.1 (maybe I can add this to cabal check as well while I'm in there).

Let me know if any of that wasn't clear.