From 328318f4e55a006709b863e531c0a03417696842 Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Wed, 23 Oct 2024 11:26:11 -0400 Subject: [PATCH] Add a note for contributors installing fourmolu - Code review suggested changes - Redundant "that". - Use indefinite article. - Assume ghc version installed via ghcup - Use `--with-compiler` option - Grammar, "its requirement" - Move --with-compiler to a tip - Use --numeric-version - Use hyphen in series-specific - Capitalise GHC - Note restriction on system ghc version. - Add a warning about switching fourmolu versions Co-Authored-By: brandon s allbery kf8nh Co-Authored-By: Artem Pelenitsyn --- CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2e28f2e069..9c974bfaa5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,15 +190,55 @@ of their patch is not influenced by their setup or implicit knowledge of the sys ## 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 -the code base. - +We use automated formatting, checked in the CI process, to enforce a unified +style across the code bases and include these makefile targets to help with +formatting: * `make style` - Format the `Cabal`, `Cabal-syntax` and `cabal-install` directories. * `make style-modified` - Format files modified in the current tree. * `make style-commit COMMIT=` - Format files modified between HEAD and the given reference. +> [!NOTE] +> We use `fourmolu-0.12.0.0` for formatting. If installing it with `cabal +> install`, please make sure to use a version of `GHC >= 9.2.1 && < 9.8`. +> Its requirement of `GHC2021` sets the lower bound, and its reliance on +> `ghc-lib-parser` sets the upper bound on GHC versions. A command for +> installing it this way is: +> +> ``` +> $ cabal install fourmolu-0.12.0.0 --overwrite-policy=always --ignore-project +> ``` + +> [!Tip] +> If you have multiple versions of GHC installed with `ghcup`, a series-specific +> GHC can be used by adding an option of `--with-compiler=ghc-x.y` (for the +> latest installed `x.y.z` version in the `x.y` series) or an option of +> `--with-compiler=ghc-x.y.z` to the above install command. +> +> ``` +> $ ghc --numeric-version +> 9.10.1 +> +> $ ghc-9.6 --numeric-version +> 9.6.6 +> +> $ ghc-9.4.8 --numeric-version +> 9.4.8 +> ``` +> +> If not using the `--with-compiler` option then the system `ghc` version should +> be one in the `ghc-9.2`, `ghc-9.4` or `ghc-9.6` series when installing +> `fourmolu`. + +> [!WARNING] +> If you have need of another `fourmolu` version for other work and want to +> switch between versions then your options are reinstalling or using a nix shell +> or something similar. It is not yet possible to specify development +> environment tools within a package with different constraints on dependencies, +> see [issue-9230][issue-9230]. + +[issue-9230]: https://github.com/haskell/cabal/issues/9230 + ## Whitespace Conventions We use automated whitespace convention checking. Violations can be fixed by