CONTRIBUTING.md

   1 # Contributing to _Black_
   2
   3 Welcome! Happy to see you willing to make the project better. Have you read the entire
   4 [user documentation](https://black.readthedocs.io/en/latest/) yet?
   5
   6 ## Bird's eye view
   7
   8 In terms of inspiration, _Black_ is about as configurable as _gofmt_. This is
   9 deliberate.
  10
  11 Bug reports and fixes are always welcome! Please follow the
  12 [issue template on GitHub](https://github.com/psf/black/issues/new) for best results.
  13
  14 Before you suggest a new feature or configuration knob, ask yourself why you want it. If
  15 it enables better integration with some workflow, fixes an inconsistency, speeds things
  16 up, and so on - go for it! On the other hand, if your answer is "because I don't like a
  17 particular formatting" then you're not ready to embrace _Black_ yet. Such changes are
  18 unlikely to get accepted. You can still try but prepare to be disappointed.
  19
  20 ## Technicalities
  21
  22 Development on the latest version of Python is preferred. As of this writing it's 3.8.
  23 You can use any operating system. I am using macOS myself and CentOS at work.
  24
  25 Install all development dependencies using:
  26
  27 ```
  28 $ pipenv install --dev
  29 $ pipenv shell
  30 $ pre-commit install
  31 ```
  32
  33 If you haven't used `pipenv` before but are comfortable with virtualenvs, just run
  34 `pip install pipenv` in the virtualenv you're already using and invoke the command above
  35 from the cloned _Black_ repo. It will do the correct thing.
  36
  37 Before submitting pull requests, run tests with:
  38
  39 ```
  40 $ python -m unittest
  41 ```
  42
  43 ## Hygiene
  44
  45 If you're fixing a bug, add a test. Run it first to confirm it fails, then fix the bug,
  46 run it again to confirm it's really fixed.
  47
  48 If adding a new feature, add a test. In fact, always add a test. But wait, before adding
  49 any large feature, first open an issue for us to discuss the idea first.
  50
  51 ## Finally
  52
  53 Thanks again for your interest in improving the project! You're taking action when most
  54 people decide to sit and watch.