feat: document pre-commit

README.md

@@ -67,3 +67,69 @@ To run (all) tests, simply use
 ```sh
 stack test
 ```
+
+## Contribute
+
+### pre-commit
+
+We use [pre-commit](https://pre-commit.com/) to ensure code quality.
+
+Collaborators **MUST** set them up before commiting any code to our repository.
+
+Otherwise, the triggered CI jobs will fail.
+
+#### Set up pre-commit
+
+1. [Install](https://pre-commit.com/#installation) `pre-commit`.
+    - Alternatively, install/make sure you have `python3` and run `pip install`.
+1. [Check it shows a version](https://pre-commit.com/#1-install-pre-commit).
+1. [Install the git hook scripts](https://pre-commit.com/#3-install-the-git-hook-scripts).
+
+#### pre-commit configs
+
+See [docs](https://pre-commit.com/#adding-pre-commit-plugins-to-your-project).
+
+Hooks:
+
+- run before a commit - [.pre-commit-config.yaml](.pre-commit-config.yaml)
+- run in CI - [.pre-commit-checks.yaml](.pre-commit-checks.yaml)
+
+You can run a specific hook (see [docs](https://pre-commit.com/#pre-commit-run)):
+
+```console
+pre-commit run -c .pre-commit-checks.yaml fourmolu-check --all
+```
+
+#### pre-commit workflow
+
+- `pre-commit` runs before a commit (at the [pre-commit phase](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks))
+  > The pre-commit hook is run first, before you even type in a commit message. It's used to inspect the snapshot that's about to be committed, to see if you've forgotten something, to make sure tests run, or to examine whatever you need to inspect in the code. Exiting non-zero from this hook aborts the commit ...
+
+- `pre-commit` stashes ([link](https://git-scm.com/docs/git-stash)) unstaged ([link](https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states)) files.
+
+    ```console
+    [WARNING] Unstaged files detected.
+    [INFO] Stashing unstaged files to /home/eyjafjallajokull/.cache/pre-commit/patch1705090051-437857.
+    ```
+
+- `pre-commit` runs hooks.
+- A hook may exit with an error, e.g.:
+
+    ```md
+    Format Haskell (.hs) files...............................................Failed
+    - hook id: fourmolu
+    - exit code: 102
+    - files were modified by this hook
+    ```
+
+  - In case of the [fourmolu](https://github.com/fourmolu/fourmolu) formatter,
+    it's assumed that formatting a formatted `Haskell` file doesn't modify it.
+    However, `pre-commit` runs the `fourmolu` hook and reports that it has modified some files.
+    This error won't allow you to commit.
+
+- `pre-commit` unstashes files.
+
+- You should stage all changes so that `pre-commit` does not complain.
+  - In case of `fourmolu`, stage the formatted code regions.
+
+- Now, you can commit.