Reorganize docs v2 (GH-2174)

[etc/vim.git] / docs / contributing / the_basics.md

diff --git a/docs/contributing_to_black.md b/docs/contributing/the_basics.md
similarity index 68%
rename from docs/contributing_to_black.md
rename to docs/contributing/the_basics.md
index b911b465afd352aae1942e849a127911a6401b8d..461bff96505c6dfd2a8b717bd0699c5afe1e3c2c 100644 (file)
--- a/docs/contributing_to_black.md
+++ b/docs/contributing/the_basics.md
@@ -1,28 +1,11 @@
-[//]: # "NOTE: THIS FILE WAS AUTOGENERATED FROM CONTRIBUTING.md"
+# The basics
 
-# 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.
-
-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.
+An overview on contributing to the _Black_ project.
 
 ## Technicalities
 
 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.
+You can use any operating system.
 
 Install all development dependencies using:
 
@@ -63,7 +46,7 @@ $ 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
+you feel this PR does 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:
 
@@ -71,11 +54,17 @@ have a line in the following format:
 - `Black` is now more awesome (#X)
 ```
 
-To workout X, please use
+Note that X should be your PR number, not issue number! 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.
@@ -96,7 +85,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).
+[documentation](./gauging_changes.md#black-primer).
 
 ## Hygiene