From 4328ce258fd5bce0bec922cfedc61fab1b9f7af5 Mon Sep 17 00:00:00 2001 From: Andreas Abel Date: Tue, 31 Aug 2021 17:25:54 +0200 Subject: [PATCH] Fix #4894: document alternatives to write a tested-with list A grab-bag of alternatives as discussed at haskell/cabal#4894. --- doc/cabal-package.rst | 69 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/doc/cabal-package.rst b/doc/cabal-package.rst index 453c8e94649..b79f3375f68 100644 --- a/doc/cabal-package.rst +++ b/doc/cabal-package.rst @@ -629,19 +629,78 @@ describe the package as a whole: and is rather intended as extra metadata for use by third party tooling, such as e.g. CI tooling. - Here's a typical usage example + Here's a typical usage example: :: - tested-with: GHC == 8.6.3, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2, + tested-with: GHC == 9.0.1, GHC == 8.10.4, GHC == 8.8.4, + GHC == 8.6.5, GHC == 8.4.4, GHC == 8.2.2, GHC == 8.0.2, GHC == 7.10.3, GHC == 7.8.4, GHC == 7.6.3, GHC == 7.4.2 - which can (starting with Cabal 3.0) also be written using the more - concise set notation syntax + The same can be spread over several lines, for instance: :: - tested-with: GHC == { 8.6.3, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 } + tested-with: GHC == 9.0.1 + , GHC == 8.10.4 + , GHC == 8.8.4 + , GHC == 8.6.5 + , GHC == 8.4.4 + , GHC == 8.2.2 + , GHC == 8.0.2 + , GHC == 7.10.3 + , GHC == 7.8.4 + , GHC == 7.6.3 + , GHC == 7.4.2 + + The separating comma can also be dropped altogether: + + :: + + tested-with: + GHC == 9.0.1 + GHC == 8.10.4 + GHC == 8.8.4 + GHC == 8.6.5 + GHC == 8.4.4 + GHC == 8.2.2 + GHC == 8.0.2 + GHC == 7.10.3 + GHC == 7.8.4 + GHC == 7.6.3 + GHC == 7.4.2 + + However, this alternative might + `disappear `__ + in the future. + + + Starting with :pkg-field:`cabal-version` 3.0, + there are further conveniences. + First, a preceding ``,`` is allowed, so a bullet-list style + is possible (recommended): + + :: + + tested-with: + , GHC == 9.0.1 + , GHC == 8.10.4 + , GHC == 8.8.4 + , GHC == 8.6.5 + , GHC == 8.4.4 + , GHC == 8.2.2 + , GHC == 8.0.2 + , GHC == 7.10.3 + , GHC == 7.8.4 + , GHC == 7.6.3 + , GHC == 7.4.2 + + + Second, a concise set notation syntax is available: + + :: + + tested-with: GHC == { 9.0.1, 8.10.4, 8.8.4, 8.6.5, 8.4.4, 8.2.2, 8.0.2, 7.10.3, 7.8.4, 7.6.3, 7.4.2 } .. pkg-field:: data-files: filename list