CONTRIBUTING.md
In lorenzwalthert/precommit: Pre-Commit Hooks

General

Before making a pull request, discuss your ideas in an issue.

Adding new hooks

To create a new hook, have a look at the official documentation on creating new hooks, then have a look at existing hooks in this repo. The actual executables are defined in inst/hooks/. In the script, you can expect the passed command line arguments to be all options, finally the files that should be processed with the hook.

For the scripts to become a hook, they need to be registered in .pre-commit-hooks.yaml. As of pre-commit 2.11, R is a supported language of pre-commit. Hence, it should have language: r in .pre-commit-hooks.yaml and then (for compatibility) a shebang in the entrypoint script.

Testing hooks

Hooks should be tested by checking both the positive outcome (hook passes) and the negative outcome (hook fails) by adding two run_test() statements to ./tests/testthat/test-hooks.R. Look at existing examples and the documentation of run_test(). Note that this won't interact with pre-commit. It will simply run Rscript path/to/script.R (whereas with pre-commit, a {renv} will be activated before running the script).

Also, there are tests to ensure that hooks are correctly registered in .pre-commit-hooks.yaml, which you have to adapt if you add a hook.

You can also test them with pre-commit try-repo as described in the documentation.

Summary

add your R (with extension) script in inst/hooks/exported and make it executable. See other scripts in inst/hooks/exported for a starting point for setting up your script.
register hook in .pre-commit-hooks.yaml.
add two unit tests, test manually with pre-commit try-repo and adapt the end-to-end test.
add a description of the new hook to vignettes/available-hooks.Rmd. Both description and yaml example code.