Adjustments to usage of pre-commit (digital-asset#15889)

- sets the default value for the hook type to `pre-push` - allows to configure the hook type using `DADE_PRE_COMMIT_HOOK_TYPE` - uninstalls all hooks with `direnv` before installation (no manual clean-up needed) - documents the usage of `pre-commit` in `README.md` - makes sure `pre-commit` is quiet when run with `direnv`
kgeonw · Jan 9, 2023 · 06e5c65 · 06e5c65
1 parent 9de4c8e
commit 06e5c65
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 3 deletions.
diff --git a/.envrc b/.envrc
@@ -1,8 +1,15 @@
 echo "[dev-env] Setting up DA Development Environment"
 eval "$(dev-env/bin/dade assist)"
 
+DADE_PRE_COMMIT_HOOK_TYPE=pre-push
+
 # Load private overrides
 [[ -f .envrc.private ]] && source_env .envrc.private
 
-# install pre-commit hook (opt-out by setting `DADE_NO_PRE_COMMIT`)
-test "x$DADE_NO_PRE_COMMIT" = x && pre-commit install
+# always start from a clean slate to ensure that the install phase produces the scenario described by `DADE_NO_PRE_COMMIT` and `DADE_PRE_COMMIT_HOOK_TYPE`
+# this is a bit unfortunate but it doesn't look like pre-commit currently supports uninstalling all hooks in one go as of version 2.20.0
+HOOK_TYPES=(pre-commit pre-merge-commit pre-push prepare-commit-msg commit-msg post-checkout post-commit post-merge post-rewrite)
+for HOOK_TYPE in ${HOOK_TYPES[@]}; do pre-commit uninstall -t "$HOOK_TYPE" > /dev/null; done
+
+# install pre-commit hook (opt-out by setting `DADE_NO_PRE_COMMIT`, set the hook type with `DADE_PRE_COMMIT_HOOK_TYPE` -- defaults to 'pre-push')
+test "x$DADE_NO_PRE_COMMIT" = x && pre-commit install -t "$DADE_PRE_COMMIT_HOOK_TYPE" > /dev/null
diff --git a/README.md b/README.md
@@ -125,14 +125,22 @@ Then start `dev-env` from PowerShell with:
 
 In all new PowerShell processes started, you need to repeat the `enable` step.
 
-### 3. First build and test
+### 3. Lint, build, and test
 
 We have a single script to build most targets and run the tests. On Linux and Mac run `./build.sh`. On Windows run `.\build.ps1`. Note that these scripts may take over an hour the first time.
 
 To just build do `bazel build //...`, and to just test do `bazel test //...`. To read more about Bazel and how to use it, see [the Bazel site](https://bazel.build).
 
 On Mac if building is causing trouble complaining about missing nix packages, you can try first running `nix-build -A tools -A cached nix` repeatedly until it completes without error.
 
+CI will run a few checks with regards to formatting, linting, presence of copyright headers, and so on. In order to make sure your PR can smoothly go through those checks, we use
+a tool called [`pre-commit`](https://pre-commit.com/). The tool is managed by Nix and you don't have to install it. If you use `direnv`, the tool will automatically install a `pre-push`
+hook that will run the relevant checks right before you push. This will give you a chance to apply necessary amendments before your contribution reaches CI. If you don't use `direnv` you
+can still use the tool by activating it manually (have a look at how it's done in `.envrc`). If you use `direnv` but prefer to not use the tool at all, you can add the line
+`export DADE_NO_PRE_COMMIT=anything_really` to `.envrc.private`. You can also customize the phase at which the hooks will run by exporting the environment variable `DADE_PRE_COMMIT_HOOK_TYPE`
+and setting it to one of the supported stages (`pre-commit` is a common choice, but the default when installed via `direnv` will be `pre-push` to reduce the times the hooks will run while
+still making sure that you can have a tight feedback loop to fix linting errors).
+
 ### 4. Installing a local copy
 
 On Linux and Mac run `daml-sdk-head` which installs a version of the SDK with version number `0.0.0`. Set the `version:` field in any Daml project to 0.0.0 and it will use the locally installed one.