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