CONTRIBUTING.md

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