Add CONTRBUTING info about CHANGES.md requirement (#2073)

[etc/vim.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4250f787185259a24eaa56b8e545d5d332b5922..8a3d8bf2830e45ac2fe6304330bf80a6207e008f 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,14 +34,57 @@ If you haven't used `pipenv` before but are comfortable with virtualenvs, just r
 `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 lints and tests with:
+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
-$ python -m unittest
+
+# 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]
 ```
 
+### News / Changelog Requirement
+
+`Black` has CI that will check for an entry corresponding to your PR in `CHANGES.md`. If
+you feel this PR not require a changelog entry please state that in a comment and a
+maintainer can add a `skip news` label to make the CI pass. Otherwise, please ensure you
+have a line in the following format:
+
+```md
+- `Black` is now more awesome (#X)
+```
+
+To workout X, checkout the latest issue and PR number and add 1. This is not perfect but
+saves a lot of release overhead as now the releaser does not need to go back and workout
+what to add to the `CHANGES.md` for each release.
+
+_Suggestions welcome on how this could be a better less invasive flow._
+
+### 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
 
 `black-primer` is used by CI to pull down well-known _Black_ formatted projects and see
@@ -52,7 +95,7 @@ your PR. You may need to change
 configuration for it to pass.
 
 For more `black-primer` information visit the
-[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md#black-primer).
+[documentation](https://github.com/psf/black/blob/master/docs/black_primer.md).
 
 ## Hygiene