haskell / haskell/cabal

Version range, definition and glossary

Open
#10,597 1 comment 1 reaction 0 assignees View on GitHub
documentation
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

![image](https://github.com/user-attachments/assets/f4495944-9e52-4c7e-a342-f58414572791)

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

![image](https://github.com/user-attachments/assets/fda55771-1b82-4cc1-9594-418140376327)

[^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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.