124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
# The basics
|
|
|
|
An overview on contributing to the _Black_ project.
|
|
|
|
## Technicalities
|
|
|
|
Development on the latest version of Python is preferred. You can use any operating
|
|
system.
|
|
|
|
Install development dependencies inside a virtual environment of your choice, for
|
|
example:
|
|
|
|
```console
|
|
$ python3 -m venv .venv
|
|
$ source .venv/bin/activate # activation for linux and mac
|
|
$ .venv\Scripts\activate # activation for windows
|
|
|
|
(.venv)$ pip install -r test_requirements.txt
|
|
(.venv)$ pip install -e .[d]
|
|
(.venv)$ pre-commit install
|
|
```
|
|
|
|
Before submitting pull requests, run lints and tests with the following commands from
|
|
the root of the black repo:
|
|
|
|
```console
|
|
# Linting
|
|
(.venv)$ pre-commit run -a
|
|
|
|
# Unit tests
|
|
(.venv)$ tox -e py
|
|
|
|
# Optional Fuzz testing
|
|
(.venv)$ tox -e fuzz
|
|
|
|
# Format Black itself
|
|
(.venv)$ tox -e run_self
|
|
```
|
|
|
|
### Development
|
|
|
|
Further examples of invoking the tests
|
|
|
|
```console
|
|
# Run all of the above mentioned, in parallel
|
|
(.venv)$ tox --parallel=auto
|
|
|
|
# Run tests on a specific python version
|
|
(.venv)$ tox -e py39
|
|
|
|
# pass arguments to pytest
|
|
(.venv)$ tox -e py -- --no-cov
|
|
|
|
# print full tree diff, see documentation below
|
|
(.venv)$ tox -e py -- --print-full-tree
|
|
|
|
# disable diff printing, see documentation below
|
|
(.venv)$ tox -e py -- --print-tree-diff=False
|
|
```
|
|
|
|
`Black` has two pytest command-line options affecting test files in `tests/data/` that
|
|
are split into an input part, and an output part, separated by a line with`# output`.
|
|
These can be passed to `pytest` through `tox`, or directly into pytest if not using
|
|
`tox`.
|
|
|
|
#### `--print-full-tree`
|
|
|
|
Upon a failing test, print the full concrete syntax tree (CST) as it is after processing
|
|
the input ("actual"), and the tree that's yielded after parsing the output ("expected").
|
|
Note that a test can fail with different output with the same CST. This used to be the
|
|
default, but now defaults to `False`.
|
|
|
|
#### `--print-tree-diff`
|
|
|
|
Upon a failing test, print the diff of the trees as described above. This is the
|
|
default. To turn it off pass `--print-tree-diff=False`.
|
|
|
|
### News / Changelog Requirement
|
|
|
|
`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
|
|
you feel this PR does not require a changelog entry please state that in a comment and a
|
|
maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
|
|
have a line in the following format:
|
|
|
|
```md
|
|
- `Black` is now more awesome (#X)
|
|
```
|
|
|
|
Note that X should be your PR number, not issue number! To workout X, please use
|
|
[Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). This
|
|
is not perfect but saves a lot of release overhead as now the releaser does not need to
|
|
go back and workout what to add to the `CHANGES.md` for each release.
|
|
|
|
### Style Changes
|
|
|
|
If a change would affect the advertised code style, please modify the documentation (The
|
|
_Black_ code style) to reflect that change. Patches that fix unintended bugs in
|
|
formatting don't need to be mentioned separately though. If the change is implemented
|
|
with the `--preview` flag, please include the change in the future style document
|
|
instead and write the changelog entry under a dedicated "Preview changes" heading.
|
|
|
|
### Docs Testing
|
|
|
|
If you make changes to docs, you can test they still build locally too.
|
|
|
|
```console
|
|
(.venv)$ pip install -r docs/requirements.txt
|
|
(.venv)$ pip install -e .[d]
|
|
(.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
|
|
```
|
|
|
|
## Hygiene
|
|
|
|
If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
|
|
run it again to confirm it's really fixed.
|
|
|
|
If adding a new feature, add a test. In fact, always add a test. But wait, before adding
|
|
any large feature, first open an issue for us to discuss the idea first.
|
|
|
|
## Finally
|
|
|
|
Thanks again for your interest in improving the project! You're taking action when most
|
|
people decide to sit and watch.
|