Version range, definition and glossary
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
For the proposed guide on freeze files, #9984, I'd like to talk about version ranges. I can't find anywhere in the users guide where "version range" is defined.
```
$ grep -R -E 'version range' ./**/*.rst
./doc/cabal-commands.rst:- ``invalid-range-tested``: invalid ``tested-with`` version range.
./doc/cabal-commands.rst:- ``impossible-dep``: impossible internal library version range dependency.
./doc/cabal-commands.rst:- ``impossible-dep-exe``: impossible internal executable version range dependency.
./doc/cabal-package-description-file.rst: followed by a version range. For example, ``GHC ==6.10.3``, or
./doc/cabal-package-description-file.rst: version ranges according to the PVP_ contract (see below).
./doc/file-format-changelog.rst:* Remove ``-any`` and ``-none`` syntax for version ranges
```
There is an indirection to https://pvp.haskell.org, `PVP_`. This page doesn't contain the phrase "version range" but it does have the word "range" in three places:
- "a way for clients to specify a particular version or range of versions of a dependency"
- "if change consist only of corrected documentation, non-visible change to allow different dependency range"
- "A client MAY specify that they are insensitive to additions to the API by allowing a range of C values"
That's it for the PVP specification. Do we need to define what this is more clearly in the users guide? Would definitions like this warrant having a glossary in the users guide?
https://github.com/haskell/cabal/blob/b62b6940b04943f18b56d9fabf6b42631c060dc7/Cabal-syntax/src/Distribution/Types/VersionRange/Internal.hs#L52-L60
There's no haddock comment introducing `VersionRange` or the ["Version ranges" section](https://hackage.haskell.org/package/Cabal-syntax-3.14.0.0/docs/Distribution-Types-VersionRange.html) but the operators are shown in the haddocks for each constructor of `VersionRangeF` [^1].
https://github.com/haskell/cabal/blob/b62b6940b04943f18b56d9fabf6b42631c060dc7/Cabal-syntax/src/Distribution/Types/VersionRange/Internal.hs#L158-L188

The `Parsec` and `Pretty` instances for `VersionRange` have some good examples.

[^1]: There are plain comments next to each constructor of `VersionRange`. This data type is in an internal module, [`Distribution.Types.VersionRange.Internal`](https://hackage.haskell.org/package/Cabal-syntax-3.14.0.0/docs/Distribution-Types-VersionRange-Internal.html)
Contributor guide
Assessment
This issue has not been assessed yet.