Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9d1342a

Browse files
asottileasottile
committed
Document adding a supported language
1 parent e0c7db1 commit 9d1342a

1 file changed

Lines changed: 98 additions & 5 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 98 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
## Local development
44

5-
- The complete test suite depends on having at least the following installed (possibly not
6-
a complete list)
5+
- The complete test suite depends on having at least the following installed
6+
(possibly not a complete list)
77
- git (A sufficiently newer version is required to run pre-push tests)
88
- python2 (Required by a test which checks different python versions)
99
- python3 (Required by a test which checks different python versions)
@@ -30,7 +30,7 @@ Running a specific test with the environment activated is as easy as:
3030

3131
### Running all the tests
3232

33-
Running all the tests can be done by running `tox -e py27` (or your
33+
Running all the tests can be done by running `tox -e py37` (or your
3434
interpreter version of choice). These often take a long time and consume
3535
significant cpu while running the slower node / ruby integration tests.
3636

@@ -49,5 +49,98 @@ Documentation is hosted at https://pre-commit.com
4949
This website is controlled through
5050
https://github.com/pre-commit/pre-commit.github.io
5151

52-
When adding a feature, please make a pull request to add yourself to the
53-
contributors list and add documentation to the website if applicable.
52+
## Adding support for a new hook language
53+
54+
pre-commit already supports many [programming languages](https://pre-commit.com/#supported-languages)
55+
to write hook executables with.
56+
57+
When adding support for a language, you must first decide what level of support
58+
to implement. The current implemented languages are at varying levels:
59+
60+
- 0th class - pre-commit does not require any dependencies for these languages
61+
as they're not actually languages (current examples: fail, pygrep)
62+
- 1st class - pre-commit will bootstrap a full interpreter requiring nothing to
63+
be installed globally (current examples: node, ruby)
64+
- 2nd class - pre-commit requires the user to install the language globally but
65+
will install tools in an isolated fashion (current examples: python, go, rust,
66+
swift, docker).
67+
- 3rd class - pre-commit requires the user to install both the tool and the
68+
language globally (current examples: script, system)
69+
70+
"third class" is usually the easiest to implement first and is perfectly
71+
acceptable.
72+
73+
Ideally the language works on the supported platforms for pre-commit (linux,
74+
windows, macos) but it's ok to skip one or more platforms (for example, swift
75+
doesn't run on windows).
76+
77+
When writing your new language, it's often useful to look at other examples in
78+
the `pre_commit/languages` directory.
79+
80+
It might also be useful to look at a recent pull request which added a
81+
language, for example:
82+
83+
- [rust](https://github.com/pre-commit/pre-commit/pull/751)
84+
- [fail](https://github.com/pre-commit/pre-commit/pull/812)
85+
- [swift](https://github.com/pre-commit/pre-commit/pull/467)
86+
87+
### `language` api
88+
89+
here are the apis that should be implemented for a language
90+
91+
Note that these are also documented in [`pre_commit/languages/all.py`](https://github.com/pre-commit/pre-commit/blob/master/pre_commit/languages/all.py)
92+
93+
#### `ENVIRONMENT_DIR`
94+
95+
a short string which will be used for the prefix of where packages will be
96+
installed. For example, python uses `py_env` and installs a `virtualenv` at
97+
that location.
98+
99+
this will be `None` for 0th / 3rd class languages as they don't have an install
100+
step.
101+
102+
#### `get_default_version`
103+
104+
This is used to retrieve the default `language_version` for a language. If
105+
one cannot be determined, return `'default'`.
106+
107+
You generally don't need to implement this on a first pass and can just use:
108+
109+
```python
110+
get_default_version = helpers.basic_default_version
111+
```
112+
113+
`python` is currently the only language which implements this api
114+
115+
#### `healthy`
116+
117+
This is used to check whether the installed environment is considered healthy.
118+
This function should return `True` or `False`.
119+
120+
You generally don't need to implement this on a first pass and can just use:
121+
122+
```python
123+
healthy = helpers.basic_healthy
124+
```
125+
126+
`python` is currently the only language which implements this api, for python
127+
it is checking whether some common dlls are still available.
128+
129+
#### `install_environment`
130+
131+
this is the trickiest one to implement and where all the smart parts happen.
132+
133+
this api should do the following things
134+
135+
- (0th / 3rd class): `install_environment = helpers.no_install`
136+
- (1st class): install a language runtime into the hook's directory
137+
- (2nd class): install the package at `.` into the `ENVIRONMENT_DIR`
138+
- (2nd class, optional): install packages listed in `additional_dependencies`
139+
into `ENVIRONMENT_DIR` (not a required feature for a first pass)
140+
141+
#### `run_hook`
142+
143+
This is usually the easiest to implement, most of them look the same as the
144+
`node` hook implementation:
145+
146+
https://github.com/pre-commit/pre-commit/blob/160238220f022035c8ef869c9a8642f622c02118/pre_commit/languages/node.py#L72-L74

0 commit comments

Comments
 (0)