speed up cache by approximately 42x by avoiding pathlib (#1953)

[etc/vim.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7008ecb309221e2d660c11216315168392216e43..571d870452bc4c6f36473d26026b5da83c915b95 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,59 +1,94 @@
-# Contributing to Black
-
-Welcome! Happy to see you willing to make the project better. Have you
-read the entire [user documentation](http://black.readthedocs.io/en/latest/)
-yet?
+# Contributing to _Black_

 
 

+Welcome! Happy to see you willing to make the project better. Have you read the entire
+[user documentation](https://black.readthedocs.io/en/latest/) yet?

 
 ## Bird's eye view
 
 
 ## Bird's eye view
 

-In terms of inspiration, *Black* is about as configurable as *gofmt* and
-*rustfmt* are.  This is deliberate.
-
-Bug reports and fixes are always welcome!  Please follow the issue
-template on GitHub for best results.
+In terms of inspiration, _Black_ is about as configurable as _gofmt_. This is
+deliberate.

 
 

-Before you suggest a new feature or configuration knob, ask yourself why
-you want it.  If it enables better integration with some workflow, fixes
-an inconsistency, speeds things up, and so on - go for it!  On the other
-hand, if your answer is "because I don't like a particular formatting"
-then you're not ready to embrace *Black* yet. Such changes are unlikely
-to get accepted. You can still try but prepare to be disappointed.
+Bug reports and fixes are always welcome! Please follow the
+[issue template on GitHub](https://github.com/psf/black/issues/new) for best results.

 
 

+Before you suggest a new feature or configuration knob, ask yourself why you want it. If
+it enables better integration with some workflow, fixes an inconsistency, speeds things
+up, and so on - go for it! On the other hand, if your answer is "because I don't like a
+particular formatting" then you're not ready to embrace _Black_ yet. Such changes are
+unlikely to get accepted. You can still try but prepare to be disappointed.

 
 ## Technicalities
 
 
 ## Technicalities
 

-Development on the latest version of Python is preferred.  As of this
-writing it's 3.6.4.  You can use any operating system.  I am using macOS
-myself and CentOS at work.
+Development on the latest version of Python is preferred. As of this writing it's 3.9.
+You can use any operating system. I am using macOS myself and CentOS at work.

 
 Install all development dependencies using:
 
 Install all development dependencies using:

-```
+
+```console

 $ pipenv install --dev
 $ pipenv install --dev

+$ pipenv shell

 $ pre-commit install
 ```
 $ pre-commit install
 ```

-If you haven't used `pipenv` before but are comfortable with virtualenvs,
-just run `pip install pipenv` in the virtualenv you're already using and
-invoke the command above from the cloned Black repo. It will do the
-correct thing.

 
 

-Before submitting pull requests, run tests with:
+If you haven't used `pipenv` before but are comfortable with virtualenvs, just run
+`pip install pipenv` in the virtualenv you're already using and invoke the command above
+from the cloned _Black_ repo. It will do the correct thing.
+
+Non pipenv install works too:
+
+```console
+$ pip install -r test_requirements
+$ pip install -e .[d]
+```
+
+Before submitting pull requests, run lints and tests with the following commands from
+the root of the black repo:
+
+```console
+# Linting
+$ pre-commit run -a
+
+# Unit tests
+$ tox -e py
+
+# Optional Fuzz testing
+$ tox -e fuzz
+
+# Optional CI run to test your changes on many popular python projects
+$ black-primer [-k -w /tmp/black_test_repos]

 ```
 ```

-$ python setup.py test
+
+### Docs Testing
+
+If you make changes to docs, you can test they still build locally too.
+
+```console
+$ pip install -r docs/requirements.txt
+$ pip install [-e] .[d]
+$ sphinx-build -a -b html -W docs/ docs/_build/

 ```
 
 ```
 

+## black-primer

 
 

-## Hygiene
+`black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
+if we get source code changes. It will error on formatting changes or errors. Please run
+before pushing your PR to see if you get the actions you would expect from _Black_ with
+your PR. You may need to change
+[primer.json](https://github.com/psf/black/blob/master/src/black_primer/primer.json)
+configuration for it to pass.

 
 

-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.
+For more `black-primer` information visit the
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
+
+## Hygiene

 
 

-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.
+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
 
 
 ## Finally
 

-Thanks again for your interest in improving the project!  You're taking
-action when most people decide to sit and watch.
+Thanks again for your interest in improving the project! You're taking action when most
+people decide to sit and watch.