Development package version naming conventions

[palmskog]

This is to document and clarify the use and non-use of ~ and other delimiters in OPAM package versions. As originally defined Debian, the use of ~ in version names affects sorting, so that 8.5~beta1 comes before both 8.5 and 8.5.0.

During the 8.7 cycle, Coq started using + instead of ~ for beta versions, as discussed in this Coq issue.

Through the magic of the usual lexical order, 8.7+beta1 will be sorted before 8.7.0, as required, but there is no guarantee in general, e.g., 8.7 < 8.7+beta1.

We should likely adopt some policy compatible with Coq's regarding uses of + and ~ in package versions. For example, if absence of ~ is guaranteed, it would be sufficient to say < "8.8" instead of < "8.8~" for Coq version bounds.

An issue in dune is somewhat related.

[Zimmi48]

FTR, but you probably already know this from reading the linked issue, the idea of using + instead of ~ / - was to give a version name whose order would be the same in opam / Debian and other distributions like Nix.

[palmskog]

@Zimmi48 given that we ideally want there to be both OPAM and Nix versions of "everything", my conclusion is that we should explicitly recommend people to use the + syntax for their beta versions and similar (and maybe even enforce it during pull request review). Or what do you think?

[Zimmi48]

We could do that but note that there is a limitation with that scheme: 8.10+beta1 is a beta version that will lead to 8.10.0. The fact that there is no specific rule about beta versions coming before normal ones when using + means that one can no longer release a beta version for each minor version, which is a scheme that some packages (e.g. Equations) have used.

More generally speaking, I'm very much in favor of thinking hard at good conventions, documenting them, and enforcing them progressively, but the first step is important and should not be neglected.