From 41c74f5330b2fead140e039f3c2f433ae27f2616 Mon Sep 17 00:00:00 2001
From: Kris Thielemans <KrisThielemans@users.noreply.github.com>
Date: Tue, 21 May 2024 09:39:26 +0100
Subject: [PATCH] use conda for pre-commit/clang-format versioning (#1435)

- use conda for pre-commit/clang-format versioning
- update devel/git-hooks.md documentation accordingly
---
 .github/workflows/pre-commit-check.yml |  7 ++--
 documentation/devel/git-hooks.md       | 47 +++++++++++++++++---------
 pre-commit-environment.yml             |  7 ++++
 3 files changed, 43 insertions(+), 18 deletions(-)
 create mode 100644 pre-commit-environment.yml

diff --git a/.github/workflows/pre-commit-check.yml b/.github/workflows/pre-commit-check.yml
index c9e8ccc750..2dae1b9ec0 100644
--- a/.github/workflows/pre-commit-check.yml
+++ b/.github/workflows/pre-commit-check.yml
@@ -8,6 +8,9 @@ jobs:
     name: pre-commit
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
-    - run: sudo apt-get install -yqq clang-format
+    - uses: conda-incubator/setup-miniconda@v3
+      with:
+          activate-environment: pre-commit-env
+          environment-file: pre-commit-environment.yml
+          auto-activate-base: false
     - uses: pre-commit/action@v3.0.0
diff --git a/documentation/devel/git-hooks.md b/documentation/devel/git-hooks.md
index 9d590b8dc1..6bb563c64a 100644
--- a/documentation/devel/git-hooks.md
+++ b/documentation/devel/git-hooks.md
@@ -1,36 +1,51 @@
 # Developer documentation: how to install (software for) git hooks
 
-You first need to have Python and pip
+We use [pre-commit](https://pre-commit.com) to check coding conventions, including
+white-space formatting rules.
 
-## Install [pre-commit](https://pre-commit.com)
-See https://pre-commit.com/#install but the following might work.
+Unfortunately, exact formatting used depends on the `clang-format` version. Therefore,
+you do have to install the same version as what is currently used in our GitHub Action.
 
-    pip install pre-commit
+## Installation of software
 
-If this fails with a permission error, try adding `--user` to the command.
+We highly recommend to use `conda`:
+```sh
+cd /whereever/STIR
+conda env create --file pre-commit-environment.yml
+conda activate pre-commit-env
+```
 
-If that fails with a message about `PyYAML` and `distutils`, try
+Alternative:
 
-    pip install --ignore-installed PyYAML
+1. Install Python and pip
 
-## Install clang-format
-### debian/Ubuntu
-    sudo apt install clang-format
-### MacOS
-    brew install clang-format
-### Others
-search the internet and tell us
+2. Install [pre-commit](https://pre-commit.com). See https://pre-commit.com/#install but the following might work.
+   ```sh
+   pip install pre-commit
+   ```
+   If this fails with a permission error, try adding `--user` to the command. If that fails with a message about `PyYAML` and `distutils`, try
+   ```sh
+   pip install --ignore-installed PyYAML
+   ```
+
+3. Install clang-format (but use correct version). At the time of writing, on Ubuntu 22.04, you can do
+   ```sh
+   sudo apt install clang-format
+   ```
 
 ## Enable pre-commit hooks
+
 ```sh
 cd /whereever/STIR
 pre-commit install
 ```
 
-If you need to work with a branch that was forked prior to in inclusion of clang-format, you will need to temporarily disable/uninstall pre-commit again:
+If you need to work with a branch that was forked prior to our use of `clang-format`, you will need to temporarily disable/uninstall pre-commit again:
 
     pre-commit uninstall
 
-or once-off with
+or one-off with
 
     git commit --no-verify
+
+You will then need to run `pre-commit run --all-files` when done before we will merge your pull request.
\ No newline at end of file
diff --git a/pre-commit-environment.yml b/pre-commit-environment.yml
new file mode 100644
index 0000000000..da97103508
--- /dev/null
+++ b/pre-commit-environment.yml
@@ -0,0 +1,7 @@
+name: pre-commit-env
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - pre-commit
+  - clang-format=14.0