Merge pull request haskell#10330 from 9999years/contributing-test-ins…

…tructions

Point out `validate.sh` more prominently in `CONTRIBUTING.md`

CONTRIBUTING.md

@@ -1,7 +1,6 @@
 # Contributing to Cabal
 
-Building Cabal for hacking
---------------------------
+## Building Cabal for hacking
 
 If you use the `cabal` executable from the latest version of the
 [cabal-install](https://hackage.haskell.org/package/cabal-install) package
@@ -58,10 +57,13 @@ $ cabal build Cabal-tests:unit-tests # build Cabal's unit test suite
 $ cabal build cabal-tests            # etc...
 ```
 
-Running tests
--------------
+## Running tests
+
+There are two ways to run tests: in CI with GitHub actions and locally with
+`./validate.sh`.
+
+### Using GitHub Actions.
 
-**Using GitHub Actions.**
 If you are not in a hurry, the most convenient way to run tests on Cabal
 is to make a branch on GitHub and then open a pull request; our
 continuous integration service on GitHub Actions builds and
@@ -85,7 +87,8 @@ Some tips for using GitHub Actions effectively:
   already failed), be nice to others and cancel the rest of the jobs,
   so that other commits on the build queue can be processed.
 
-**How to debug a failing CI test.**
+### How to debug a failing CI test.
+
 One of the annoying things about running tests on CI is when they
 fail, there is often no easy way to further troubleshoot the broken
 build.  Here are some guidelines for debugging continuous integration
@@ -113,7 +116,11 @@ failures:
 If none of these let you reproduce, there might be some race condition
 or continuous integration breakage; please file a bug.
 
-**Running tests locally.**
+### Running tests locally.
+
+The [`./validate.sh`](./validate.sh) script runs all the test suites. It takes
+various options to restrict the test suites it runs; use `--help` to list them.
+
 To run tests locally with `cabal`, you will need to know the
 name of the test suite you want.  Cabal and cabal-install have
 several.  Also, you'll want to read [Where are my build products?](http://cabal.readthedocs.io/en/latest/nix-local-build.html#where-are-my-build-products)
@@ -150,8 +157,7 @@ For these test executables, `-p` which applies a regex filter to the test
 names. When running `cabal-install` test suites, one need only use `cabal test` or
 `cabal run <test-target>` in order to test locally.
 
-QA Notes
---------
+## QA Notes
 
 Manual Quality Assurance (QA) is performed to ensure that the changes impacting
 the command-line interface, whether adding or modifying a behaviour,
@@ -162,20 +168,20 @@ Contributions that touch `cabal-install` are expected to include notes for the Q
 They are a description of an expected result upon calling `cabal-install` with certain parameters,
 and should be written in the body of the ticket or PR under their own heading, like this:
 
-For instance:
+```markdown
+## QA Notes
 
-> \#\# QA Notes
->
-> Calling `cabal haddock-project` should produce documentation for the whole cabal project with the following defaults enabled:
-> * Documentation lives in ./haddocks
-> * The file `./haddocks/index.html` should exist
+Calling `cabal haddock-project` should produce documentation for the whole
+cabal project with the following defaults enabled:
+* Documentation lives in ./haddocks
+* The file `./haddocks/index.html` should exist
+```
 
 Manual QA is not expected to find every possible bug, but to really challenge the assumptions of the contributor, and to verify that their own testing
 of their patch is not influenced by their setup or implicit knowledge of the system.
 
 
-Code Style
----------------
+## Code Style
 
 We use automated formatting with Fourmolu to enforce a unified style across the code bases. It is checked in the CI process.
 After installing Fourmolu 0.12, there are some makefile targets to help formatting
@@ -186,15 +192,13 @@ the code base.
 * `make style-modified` - Format files modified in the current tree.
 * `make style-commit COMMIT=<ref>` - Format files modified between HEAD and the given reference.
 
-Whitespace Conventions
-----------------------
+## Whitespace Conventions
 
 We use automated whitespace convention checking. Violations can be fixed by
 running [fix-whitespace](https://hackage.haskell.org/package/fix-whitespace). If
 you push a fix of a whitespace violation, please do so in a _separate commit_.
 
-Other Conventions
------------------
+## Other Conventions
 
 * Format your commit messages [in the standard way](https://chris.beams.io/posts/git-commit/#seven-rules).
 
@@ -254,8 +258,7 @@ Other Conventions
   #endif
   ```
 
-GitHub Ticket Conventions
--------------------
+## GitHub Ticket Conventions
 
 Each major `Cabal`/`cabal-install` release (e.g. 3.4, 3.6, etc.) has a
 corresponding GitHub Project and milestone. A ticket is included in a release's
@@ -268,8 +271,7 @@ accepting a fix in that release, i.e. we would very much appreciate someone
 working on it, but are not committing to actively sourcing someone to work on
 it.
 
-GitHub Pull Request Conventions
--------------------
+## GitHub Pull Request Conventions
 
 Every (non-backport) pull request has to go through a review and get 2
 approvals. After this is done, the author of the pull request is expected to add
@@ -310,8 +312,7 @@ think it does not warrant an issue). Feel free to open a new issue (or new
 issues) when appropriate.
 
 
-Changelog
----------
+## Changelog
 
 Anything that changes `cabal-install:exe:cabal` or changes exports from library
 modules or changes behaviour of functions exported from packages published to
@@ -365,8 +366,7 @@ At release time, the entries will be merged with
 In addition, if you're changing the `.cabal` file format specification you should
 add an entry in `doc/file-format-changelog.rst`.
 
-Communicating
--------------
+## Communicating
 
 There are a few main venues of communication:
 
@@ -379,17 +379,15 @@ There are a few main venues of communication:
   * You can join the channel using a web client, even anonymously: https://web.libera.chat/#hackage
   * Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:libera.chat
 
-Releases
---------
+## Releases
 
 Notes for how to make a release are at the
 wiki page ["Making a release"](https://github.com/haskell/cabal/wiki/Making-a-release).
 Currently, [@emilypi](https://github.com/emilypi), [@fgaz](https://github.com/fgaz) and [@Mikolaj](https://github.com/Mikolaj) have access to
 `haskell.org/cabal`, and [@Mikolaj](https://github.com/Mikolaj) is the point of contact for getting
 permissions.
 
-Preview Releases
-----------------
+## Preview Releases
 
 We make preview releases available to facilitate testing of development builds.
 
@@ -407,17 +405,15 @@ To reproduce these locally, set up an Alpine build environment using GHCup,
 and then build by calling `cabal build cabal-install --enable-executable-static`.
 
 
-API Documentation
------------------
+## API Documentation
 
 Auto-generated API documentation for the `master` branch of Cabal is automatically uploaded here: http://haskell.github.io/cabal-website/doc/html/Cabal/.
 
 ## Issue triage [![Open Source Helpers](https://www.codetriage.com/haskell/cabal/badges/users.svg)](https://www.codetriage.com/haskell/cabal)
 
 You can contribute by triaging issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to cabal on CodeTriage](https://www.codetriage.com/haskell/cabal).
 
-Hackage Revisions
------------------
+## Hackage Revisions
 
 We are reactive rather than proactive with revising bounds on our dependencies
 for code already released on Hackage. If you would benefit from a version bump,