docs/contributing/the_basics.md

   1 # The basics
   2
   3 An overview on contributing to the _Black_ project.
   4
   5 ## Technicalities
   6
   7 Development on the latest version of Python is preferred. As of this writing it's 3.9.
   8 You can use any operating system.
   9
  10 Install development dependencies inside a virtual environment of your choice, for
  11 example:
  12
  13 ```console
  14 $ python3 -m venv .venv
  15 $ source .venv/bin/activate
  16 (.venv)$ pip install -r test_requirements.txt
  17 (.venv)$ pip install -e .[d]
  18 (.venv)$ pre-commit install
  19 ```
  20
  21 Before submitting pull requests, run lints and tests with the following commands from
  22 the root of the black repo:
  23
  24 ```console
  25 # Linting
  26 (.venv)$ pre-commit run -a
  27
  28 # Unit tests
  29 (.venv)$ tox -e py
  30
  31 # Optional Fuzz testing
  32 (.venv)$ tox -e fuzz
  33 ```
  34
  35 ### News / Changelog Requirement
  36
  37 `Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
  38 you feel this PR does not require a changelog entry please state that in a comment and a
  39 maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
  40 have a line in the following format:
  41
  42 ```md
  43 - `Black` is now more awesome (#X)
  44 ```
  45
  46 Note that X should be your PR number, not issue number! To workout X, please use
  47 [Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). This
  48 is not perfect but saves a lot of release overhead as now the releaser does not need to
  49 go back and workout what to add to the `CHANGES.md` for each release.
  50
  51 ### Style Changes
  52
  53 If a change would affect the advertised code style, please modify the documentation (The
  54 _Black_ code style) to reflect that change. Patches that fix unintended bugs in
  55 formatting don't need to be mentioned separately though. If the change is implemented
  56 with the `--preview` flag, please include the change in the future style document
  57 instead and write the changelog entry under a dedicated "Preview changes" heading.
  58
  59 ### Docs Testing
  60
  61 If you make changes to docs, you can test they still build locally too.
  62
  63 ```console
  64 (.venv)$ pip install -r docs/requirements.txt
  65 (.venv)$ pip install [-e] .[d]
  66 (.venv)$ sphinx-build -a -b html -W docs/ docs/_build/
  67 ```
  68
  69 ## Hygiene
  70
  71 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
  72 run it again to confirm it's really fixed.
  73
  74 If adding a new feature, add a test. In fact, always add a test. But wait, before adding
  75 any large feature, first open an issue for us to discuss the idea first.
  76
  77 ## Finally
  78
  79 Thanks again for your interest in improving the project! You're taking action when most
  80 people decide to sit and watch.