Skip to content

Commit 679bfdc

Browse files
committed
docs(contributing): add pre-commit guide
Goes through installation, enabling the hooks and basic guidance during use.
1 parent 0b72f7b commit 679bfdc

File tree

1 file changed

+57
-0
lines changed

1 file changed

+57
-0
lines changed

CONTRIBUTING.md

+57
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,63 @@ General guidelines about naming policy (applies to package, module, function, cl
7575

7676
## Code style
7777

78+
### pre-commit
79+
80+
The repository contains a `.pre-commit-config.yaml` file that has configuration
81+
to run a set of [`pre-commit`](https://pre-commit.com) hooks. As the name
82+
implies, they run before committing code and reject commits that would include
83+
code that is not formatted or contains linting errors. `pre-commit` must be
84+
installed on your system **and** the hooks must be enabled within your local
85+
copy of the repository to run.
86+
87+
To install `pre-commit` on Debian or Ubuntu -based systems with `apt` as
88+
the package manager you should be able to run:
89+
90+
``` console
91+
apt update
92+
apt install pre-commit
93+
```
94+
95+
Alternatively, it can be installed with the system installation of `Python`:
96+
97+
``` console
98+
pip install pre-commit
99+
```
100+
101+
Visit the `pre-commit` website for more guidance on various system installation
102+
methods (<https://pre-commit.com>).
103+
104+
To enable the hooks locally, enter the directory with your local
105+
version of `eis_toolkit`, and run:
106+
107+
``` console
108+
pre-commit install
109+
```
110+
111+
Within this local repository, before any commits, the hooks should now run.
112+
Note that the `black` formatting hook will modify files and consequently, the
113+
edits by `pre-commit` will be unstaged. Stage the changes to add them back to
114+
the commit.
115+
116+
To disable the hooks and allow commits even with errors pointed out by
117+
`pre-commit`, you can add the `--no-verify` option to the `git` command-line:
118+
119+
``` console
120+
git commit -m "<message>" --no-verify
121+
```
122+
123+
However, this is not recommended and you should instead fix any issues pointed
124+
out by `pre-commit`.
125+
126+
You can also run the hooks without committing on all files. Make sure you save
127+
any text changes as `pre-commit` can modify unformatted files:
128+
129+
``` console
130+
pre-commit run --all-files
131+
```
132+
133+
### invoke
134+
78135
In order to guarantee consistent coding style, a bunch of different linters and formatters have been brought into use.
79136

80137
> **Please** note that running code style checks is not optional!

0 commit comments

Comments
 (0)