From de89ffe7f4d88a086ee76dab5e45bd8fadb53b60 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Wed, 15 May 2024 07:08:49 -0400
Subject: [PATCH] Recommend using latest cabal-install

- Shorten the suggestion to use cabal.release.project
- Move up cabal.release.project for initial build
- Put the --project-file option after as suggested by the command help
- Usage: cabal build [TARGETS] [FLAGS]
- Use the latest markup for note
- $ prefix for command line
---
 CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 062ee73f3d5..fa1d5385d68 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,19 +3,41 @@
 Building Cabal for hacking
 --------------------------
 
-If you use the latest version of cabal published on Hackage, it is sufficient to run:
+If you use the `cabal` executable from the latest version of the
+[cabal-install](https://hackage.haskell.org/package/cabal-install) package
+published on Hackage, it is sufficient to run:
 
 ```
-cabal build cabal
+$ cabal build cabal
 ```
 
-If not, you aren't able to build the testsuite, so you need to disable the default `cabal.project` that implies configuring the testsuite, e.g., with:
+If you have trouble building the testsuite for this initial build, try building
+with the release project that excludes this testsuite:
 
 ```
-cabal build --project-file=cabal.release.project cabal
+$ cabal build cabal --project-file=cabal.release.project
 ```
 
-> **Note**
+> [!NOTE]
+> The default `cabal.project` is picked up implicitly as if the
+> `--project-file=cabal.project` explicit option had been given.
+
+For developing, we recommend using the locally built version of `cabal`, the
+executable, if only because one of the released versions available may be
+lacking a fix. This can be installed:
+
+```
+$ cabal install cabal-install:exe:cabal --overwrite-policy=always
+```
+
+It can be run without first installing it with `cabal run cabal --` followed by
+its own arguments, as shown here for `build --help`:
+
+```
+$ cabal run cabal -- build --help
+```
+
+> [!NOTE]
 > If you're using Nix, you might find it convenient to work within a shell that has all the `Cabal` development dependencies:
 > ```
 > $ nix-shell -p cabal-install ghc ghcid haskellPackages.fourmolu_0_12_0_0 pkgconfig zlib.dev
@@ -30,9 +52,9 @@ to find the binary (or just run `find -type f -executable -name cabal`).
 Here are some other useful variations on the commands:
 
 ```
-cabal build Cabal # build library only
-cabal build Cabal-tests:unit-tests # build Cabal's unit test suite
-cabal build cabal-tests # etc...
+$ cabal build Cabal                  # build library only
+$ cabal build Cabal-tests:unit-tests # build Cabal's unit test suite
+$ cabal build cabal-tests            # etc...
 ```
 
 Running tests