X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/be35b1ed2d1f9453090bb29ac24abe997815ff70..89a856d742d31054bc31a6ff7ffc6ad2d24377d5:/CONTRIBUTING.md?ds=sidebyside diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72ffa56..f2a4ee2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,61 +1,116 @@ -# 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? +# 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 -In terms of inspiration, *Black* is about as configurable as *gofmt*. -This is deliberate. - -Bug reports and fixes are always welcome! Please follow the [issue -template on GitHub](https://github.com/psf/black/issues/new) 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 -Development on the latest version of Python is preferred. As of this -writing it's 3.8. 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: -``` + +```console $ pipenv install --dev $ pipenv shell $ 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] ``` -$ python setup.py test + +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] ``` +### News / Changelog Requirement -## Hygiene +`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: -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. +```md +- `Black` is now more awesome (#X) +``` + +To workout X, please use +[Next PR Number](https://ichard26.github.io/next-pr-number/?owner=psf&name=black). 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. + +### Style Changes + +If a change would affect the advertised code style, please modify the documentation (The +_Black_ code style) to reflect that change. Patches that fix unintended bugs in +formatting don't need to be mentioned separately though. + +### 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 +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. + +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 -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.