Version range, definition and glossary

[philderbeast]

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?

cabal/Cabal-syntax/src/Distribution/Types/VersionRange/Internal.hs

Lines 52 to 60 in b62b694

	data VersionRange
	= ThisVersion Version -- = version
	| LaterVersion Version -- > version (NB. not >=)
	| OrLaterVersion Version -- >= version
	| EarlierVersion Version -- < version
	| OrEarlierVersion Version -- <= version
	| MajorBoundVersion Version -- @^>= ver@ (same as >= ver && < MAJ(ver)+1)
	| UnionVersionRanges VersionRange VersionRange
	| IntersectVersionRanges VersionRange VersionRange

There's no haddock comment introducing VersionRange or the "Version ranges" section but the operators are shown in the haddocks for each constructor of VersionRangeF ¹.

cabal/Cabal-syntax/src/Distribution/Types/VersionRange/Internal.hs

Lines 158 to 188 in b62b694

	-- | F-Algebra of 'VersionRange'. See 'cataVersionRange'.
	--
	-- @since 2.2
	data VersionRangeF a
	= -- | @== version@.
	ThisVersionF Version
	| -- | @> version@. NB: not @>=@
	LaterVersionF Version
	| -- | @>= version@.
	OrLaterVersionF Version
	| -- | @< version@.
	EarlierVersionF Version
	| -- | @<= version@.
	OrEarlierVersionF Version
	| -- | @^>= version@, same as @>= version && < MAJ(version)+1@.
	MajorBoundVersionF Version
	| -- | @||@.
	UnionVersionRangesF a a
	| -- | @&&@.
	IntersectVersionRangesF a a
	deriving
	( Data
	, Eq
	, Generic
	, Read
	, Show
	, Typeable
	, Functor
	, Foldable
	, Traversable
	)

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

Footnotes

1. There are plain comments next to each constructor of VersionRange. This data type is in an internal module, Distribution.Types.VersionRange.Internal ↩

[philderbeast]

There are more hits, looking for "version bound" in the docs:

$ grep -R -E 'version bound' ./**/*.rst
./doc/cabal-commands.rst:Manually updating dependency version bounds in a ``.cabal`` file or a
./doc/cabal-commands.rst:version on Hackage that is outside the version bound specified in the
./doc/cabal-commands.rst:    Read dependency version bounds from the freeze file.
./doc/cabal-commands.rst:    Read dependency version bounds from the v2-style freeze file
./doc/cabal-commands.rst:    Read dependency version bounds from the v2-style freeze file
./doc/cabal-commands.rst:    Don't warn about outdated dependency version bounds for the packages in this list.
./doc/cabal-package-description-file.rst:    executable itself, separated by a colon, and optionally followed by a version bound.
./doc/cabal-package-description-file.rst:    1. External dependencies can (and should) contain a version bound like conventional
./doc/cabal-package-description-file.rst:    2. Internal dependencies should not contain a version bound, as they will be always
./doc/cabal-package-description-file.rst:       Specifically, version bounds that include the package's version will be warned for
./doc/cabal-package-description-file.rst:       being extraneous, and version bounds that exclude the package's version will raise
./doc/cabal-package-description-file.rst:    Each may be followed by an optional version bound.
./doc/cabal-package-description-file.rst:    In either case, the optional version bound is passed through unchanged.
./doc/cabal-package-description-file.rst:    Refer to the documentation for :pkg-field:`build-tool-depends` to understand the desugared field's meaning, along with restrictions on version bounds.
./doc/cabal-project-description-file.rst:.. cfg-field:: extra-packages: package list with version bounds (comma separated)
./doc/cabal-project-description-file.rst:    Add extra constraints to the version bounds, flag settings,
./doc/cabal-project-description-file.rst:    constraints at once. For example, to specify both version bounds and
./doc/getting-started.rst:    The version bounds on base, a boot library distributed with GHC
./doc/getting-started.rst:    version bounds.
./doc/getting-started.rst:    Widening or dropping version bound constraints on *packages included with
./doc/setup-commands.rst:    Yet extra pseudo version bounds are available here in addition: