]> git.madduck.net Git - etc/vim.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Add issue triage documentation (#2236)
authorRichard Si <63936253+ichard26@users.noreply.github.com>
Sun, 16 May 2021 16:07:27 +0000 (12:07 -0400)
committerGitHub <noreply@github.com>
Sun, 16 May 2021 16:07:27 +0000 (18:07 +0200)
* Add issue triage documentation

Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Pipfile
Pipfile.lock
docs/conf.py
docs/contributing/index.rst
docs/contributing/issue_triage.md [new file with mode: 0644]
docs/requirements.txt

diff --git a/Pipfile b/Pipfile
index b38595711378a3b26bd7d04cc2b9d47ac3a1aaba..789d97c3cbc9bd10158f17c08ff9b8b369edef37 100644 (file)
--- a/Pipfile
+++ b/Pipfile
@@ -14,6 +14,7 @@ pre-commit = "*"
 readme_renderer = "*"
 MyST-Parser = ">=0.13.7"
 sphinxcontrib-programoutput = ">=0.17"
 readme_renderer = "*"
 MyST-Parser = ">=0.13.7"
 sphinxcontrib-programoutput = ">=0.17"
+sphinx-copybutton = ">=0.3.0"
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
 setuptools = ">=39.2.0"
 setuptools-scm = "*"
 twine = ">=1.11.0"
@@ -22,7 +23,7 @@ black = {editable = true, extras = ["d"], path = "."}
 
 [packages]
 aiohttp = ">=3.6.0"
 
 [packages]
 aiohttp = ">=3.6.0"
-aiohttp-cors = "*"
+aiohttp-cors = ">=0.4.0"
 appdirs = "*"
 click = ">=7.1.2"
 mypy_extensions = ">=0.4.3"
 appdirs = "*"
 click = ">=7.1.2"
 mypy_extensions = ">=0.4.3"
index 0b9e529e73b5a7a1e1c4c1345e40ef38edad9850..b6dfe438e9e37b9891991556d5bfe9ef142eee4f 100644 (file)
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
 {
     "_meta": {
         "hash": {
-            "sha256": "fdfbacb362e4514e588736a7e8783837cb5e3aa2fbab98ea17894fdb50d51a8e"
+            "sha256": "b450e698cfe4d856397cb9d0695dcd74eb97b1d234de273179d78c0d0efccd0f"
         },
         "pipfile-spec": 6,
         "requires": {},
         },
         "pipfile-spec": 6,
         "requires": {},
         },
         "click": {
             "hashes": [
         },
         "click": {
             "hashes": [
-                "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a",
-                "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc"
+                "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136",
+                "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db"
             ],
             "index": "pypi",
             ],
             "index": "pypi",
-            "version": "==7.1.2"
+            "version": "==8.0.0"
         },
         "dataclasses": {
             "hashes": [
         },
         "dataclasses": {
             "hashes": [
         },
         "click": {
             "hashes": [
         },
         "click": {
             "hashes": [
-                "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a",
-                "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc"
+                "sha256:7d8c289ee437bcb0316820ccee14aefcb056e58d31830ecab8e47eda6540e136",
+                "sha256:e90e62ced43dc8105fb9a26d62f0d9340b5c8db053a814e25d95c19873ae87db"
             ],
             "index": "pypi",
             ],
             "index": "pypi",
-            "version": "==7.1.2"
+            "version": "==8.0.0"
         },
         "colorama": {
             "hashes": [
         },
         "colorama": {
             "hashes": [
         },
         "jinja2": {
             "hashes": [
         },
         "jinja2": {
             "hashes": [
-                "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419",
-                "sha256:a6d58433de0ae800347cab1fa3043cebbabe8baa9d29e668f1c768cb87a333c6"
+                "sha256:2f2de5285cf37f33d33ecd4a9080b75c87cd0c1994d5a9c6df17131ea1f049c6",
+                "sha256:ea8d7dd814ce9df6de6a761ec7f1cac98afe305b8cdc4aaae4e114b8d8ce24c5"
             ],
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
-            "version": "==2.11.3"
+            "markers": "python_version >= '3.6'",
+            "version": "==3.0.0"
         },
         "keyring": {
             "hashes": [
         },
         "keyring": {
             "hashes": [
         },
         "markupsafe": {
             "hashes": [
         },
         "markupsafe": {
             "hashes": [
-                "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473",
-                "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161",
-                "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235",
-                "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5",
-                "sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42",
-                "sha256:195d7d2c4fbb0ee8139a6cf67194f3973a6b3042d742ebe0a9ed36d8b6f0c07f",
-                "sha256:22c178a091fc6630d0d045bdb5992d2dfe14e3259760e713c490da5323866c39",
-                "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff",
-                "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b",
-                "sha256:2beec1e0de6924ea551859edb9e7679da6e4870d32cb766240ce17e0a0ba2014",
-                "sha256:3b8a6499709d29c2e2399569d96719a1b21dcd94410a586a18526b143ec8470f",
-                "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1",
-                "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e",
-                "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183",
-                "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66",
-                "sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b",
-                "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1",
-                "sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15",
-                "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1",
-                "sha256:6f1e273a344928347c1290119b493a1f0303c52f5a5eae5f16d74f48c15d4a85",
-                "sha256:6fffc775d90dcc9aed1b89219549b329a9250d918fd0b8fa8d93d154918422e1",
-                "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e",
-                "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b",
-                "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905",
-                "sha256:7fed13866cf14bba33e7176717346713881f56d9d2bcebab207f7a036f41b850",
-                "sha256:84dee80c15f1b560d55bcfe6d47b27d070b4681c699c572af2e3c7cc90a3b8e0",
-                "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735",
-                "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d",
-                "sha256:98bae9582248d6cf62321dcb52aaf5d9adf0bad3b40582925ef7c7f0ed85fceb",
-                "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e",
-                "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d",
-                "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c",
-                "sha256:a6a744282b7718a2a62d2ed9d993cad6f5f585605ad352c11de459f4108df0a1",
-                "sha256:acf08ac40292838b3cbbb06cfe9b2cb9ec78fce8baca31ddb87aaac2e2dc3bc2",
-                "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21",
-                "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2",
-                "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5",
-                "sha256:b1dba4527182c95a0db8b6060cc98ac49b9e2f5e64320e2b56e47cb2831978c7",
-                "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b",
-                "sha256:b7d644ddb4dbd407d31ffb699f1d140bc35478da613b441c582aeb7c43838dd8",
-                "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6",
-                "sha256:bf5aa3cbcfdf57fa2ee9cd1822c862ef23037f5c832ad09cfea57fa846dec193",
-                "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f",
-                "sha256:caabedc8323f1e93231b52fc32bdcde6db817623d33e100708d9a68e1f53b26b",
-                "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f",
-                "sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2",
-                "sha256:d53bc011414228441014aa71dbec320c66468c1030aae3a6e29778a3382d96e5",
-                "sha256:d73a845f227b0bfe8a7455ee623525ee656a9e2e749e4742706d80a6065d5e2c",
-                "sha256:d9be0ba6c527163cbed5e0857c451fcd092ce83947944d6c14bc95441203f032",
-                "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
-                "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be",
-                "sha256:feb7b34d6325451ef96bc0e36e1a6c0c1c64bc1fbec4b854f4529e51887b1621"
+                "sha256:007dc055dbce5b1104876acee177dbfd18757e19d562cd440182e1f492e96b95",
+                "sha256:031bf79a27d1c42f69c276d6221172417b47cb4b31cdc73d362a9bf5a1889b9f",
+                "sha256:161d575fa49395860b75da5135162481768b11208490d5a2143ae6785123e77d",
+                "sha256:24bbc3507fb6dfff663af7900a631f2aca90d5a445f272db5fc84999fa5718bc",
+                "sha256:2efaeb1baff547063bad2b2893a8f5e9c459c4624e1a96644bbba08910ae34e0",
+                "sha256:32200f562daaab472921a11cbb63780f1654552ae49518196fc361ed8e12e901",
+                "sha256:3261fae28155e5c8634dd7710635fe540a05b58f160cef7713c7700cb9980e66",
+                "sha256:3b54a9c68995ef4164567e2cd1a5e16db5dac30b2a50c39c82db8d4afaf14f63",
+                "sha256:3c352ff634e289061711608f5e474ec38dbaa21e3e168820d53d5f4015e5b91b",
+                "sha256:3fb47f97f1d338b943126e90b79cad50d4fcfa0b80637b5a9f468941dbbd9ce5",
+                "sha256:441ce2a8c17683d97e06447fcbccbdb057cbf587c78eb75ae43ea7858042fe2c",
+                "sha256:45535241baa0fc0ba2a43961a1ac7562ca3257f46c4c3e9c0de38b722be41bd1",
+                "sha256:4aca81a687975b35e3e80bcf9aa93fe10cd57fac37bf18b2314c186095f57e05",
+                "sha256:4cc563836f13c57f1473bc02d1e01fc37bab70ad4ee6be297d58c1d66bc819bf",
+                "sha256:4fae0677f712ee090721d8b17f412f1cbceefbf0dc180fe91bab3232f38b4527",
+                "sha256:58bc9fce3e1557d463ef5cee05391a05745fd95ed660f23c1742c711712c0abb",
+                "sha256:664832fb88b8162268928df233f4b12a144a0c78b01d38b81bdcf0fc96668ecb",
+                "sha256:70820a1c96311e02449591cbdf5cd1c6a34d5194d5b55094ab725364375c9eb2",
+                "sha256:79b2ae94fa991be023832e6bcc00f41dbc8e5fe9d997a02db965831402551730",
+                "sha256:83cf0228b2f694dcdba1374d5312f2277269d798e65f40344964f642935feac1",
+                "sha256:87de598edfa2230ff274c4de7fcf24c73ffd96208c8e1912d5d0fee459767d75",
+                "sha256:8f806bfd0f218477d7c46a11d3e52dc7f5fdfaa981b18202b7dc84bbc287463b",
+                "sha256:90053234a6479738fd40d155268af631c7fca33365f964f2208867da1349294b",
+                "sha256:a00dce2d96587651ef4fa192c17e039e8cfab63087c67e7d263a5533c7dad715",
+                "sha256:a08cd07d3c3c17cd33d9e66ea9dee8f8fc1c48e2d11bd88fd2dc515a602c709b",
+                "sha256:a19d39b02a24d3082856a5b06490b714a9d4179321225bbf22809ff1e1887cc8",
+                "sha256:d00a669e4a5bec3ee6dbeeeedd82a405ced19f8aeefb109a012ea88a45afff96",
+                "sha256:dab0c685f21f4a6c95bfc2afd1e7eae0033b403dd3d8c1b6d13a652ada75b348",
+                "sha256:df561f65049ed3556e5b52541669310e88713fdae2934845ec3606f283337958",
+                "sha256:e4570d16f88c7f3032ed909dc9e905a17da14a1c4cfd92608e3fda4cb1208bbd",
+                "sha256:e77e4b983e2441aff0c0d07ee711110c106b625f440292dfe02a2f60c8218bd6",
+                "sha256:e79212d09fc0e224d20b43ad44bb0a0a3416d1e04cf6b45fed265114a5d43d20",
+                "sha256:f58b5ba13a5689ca8317b98439fccfbcc673acaaf8241c1869ceea40f5d585bf",
+                "sha256:fef86115fdad7ae774720d7103aa776144cf9b66673b4afa9bcaa7af990ed07b"
             ],
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.1.1"
+            "markers": "python_version >= '3.6'",
+            "version": "==2.0.0"
         },
         "mccabe": {
             "hashes": [
         },
         "mccabe": {
             "hashes": [
             "index": "pypi",
             "version": "==3.5.4"
         },
             "index": "pypi",
             "version": "==3.5.4"
         },
+        "sphinx-copybutton": {
+            "hashes": [
+                "sha256:0e0461df394515284e3907e3f418a0c60ef6ab6c9a27a800c8552772d0a402a2",
+                "sha256:5125c718e763596e6e52d92e15ee0d6f4800ad3817939be6dee51218870b3e3d"
+            ],
+            "index": "pypi",
+            "version": "==0.3.1"
+        },
         "sphinxcontrib-applehelp": {
             "hashes": [
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
         "sphinxcontrib-applehelp": {
             "hashes": [
                 "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
index 7162f13dd41c062088e105f50cafdd0b80575cb1..15adb5df7a1c6b6baa3ed47bd318e5150a0c4ad0 100644 (file)
@@ -60,6 +60,7 @@ extensions = [
     "sphinx.ext.napoleon",
     "myst_parser",
     "sphinxcontrib.programoutput",
     "sphinx.ext.napoleon",
     "myst_parser",
     "sphinxcontrib.programoutput",
+    "sphinx_copybutton",
 ]
 
 # If you need extensions of a certain version or higher, list them here.
 ]
 
 # If you need extensions of a certain version or higher, list them here.
index e7a7f9fb231c28ce1d1fcfbb14692ad50b0d6be3..7e3a90905cd85ae29036d898a6164a816ce9ae04 100644 (file)
@@ -6,6 +6,7 @@ Contributing
 
   the_basics
   gauging_changes
 
   the_basics
   gauging_changes
+  issue_triage
   release_process
   reference/reference_summary
 
   release_process
   reference/reference_summary
 
diff --git a/docs/contributing/issue_triage.md b/docs/contributing/issue_triage.md
new file mode 100644 (file)
index 0000000..780b2b5
--- /dev/null
@@ -0,0 +1,167 @@
+# Issue triage
+
+Currently, _Black_ uses the issue tracker for bugs, feature requests, proposed design
+modifications, and general user support. Each of these issues have to be triaged so they
+can be eventually be resolved somehow. This document outlines the triaging process and
+also the current guidelines and recommendations.
+
+```{tip}
+If you're looking for a way to contribute without submitting patches, this might be
+the area for you. Since _Black_ is a popular project, its issue tracker is quite busy
+and always needs more attention than is available. While triage isn't the most
+glamorous or technically challenging form of contribution, it's still important.
+For example, we would love to know whether that old bug report is still reproducible!
+
+You can get easily started by reading over this document and then responding to issues.
+
+If you contribute enough and have stayed for a long enough time, you may even be
+given Triage permissions!
+```
+
+## The basics
+
+_Black_ gets a whole bunch of different issues, they range from bug reports to user
+support issues. To triage is to identify, organize, and kickstart the issue's journey
+through its lifecycle to resolution.
+
+More specifically, to triage an issue means to:
+
+- identify what type and categories the issue falls under
+- confirm bugs
+- ask questions / for further information if necessary
+- link related issues
+- provide the first initial feedback / support
+
+Note that triage is typically the first response to an issue, so don't fret if the issue
+doesn't make much progress after initial triage. The main goal of triaging to prepare
+the issue for future more specific development or discussion, so _eventually_ it will be
+resolved.
+
+The lifecycle of a bug report or user support issue typically goes something like this:
+
+1. _the issue is waiting for triage_
+2. **identified** - has been marked with a type label and other relevant labels, more
+   details or a functional reproduction may be still needed (and therefore should be
+   marked with `S: needs repro` or `S: awaiting reponse`)
+3. **confirmed** - the issue can reproduced and necessary details have been provided
+4. **discussion** - initial triage has been done and now the general details on how the
+   issue should be best resolved are being hashed out
+5. **awaiting fix** - no further discussion on the issue is necessary and a resolving PR
+   is the next step
+6. **closed** - the issue has been resolved, reasons include:
+   - the issue couldn't be reproduced
+   - the issue has been fixed
+   - duplicate of another pre-existing issue or is invalid
+
+For enhancement, documentation, and design issues, the lifecycle looks very similar but
+the details are different:
+
+1. _the issue is waiting for triage_
+2. **identified** - has been marked with a type label and other relevant labels
+3. **discussion** - the merits of the suggested changes are currently being discussed, a
+   PR would be acceptable but would be at sigificant risk of being rejected
+4. **accepted & awaiting PR** - it's been determined the suggested changes are OK and a
+   PR would be welcomed (`S: accepted`)
+5. **closed**: - the issue has been resolved, reasons include:
+   - the suggested changes were implemented
+   - it was rejected (due to technical concerns, ethos conflicts, etc.)
+   - duplicate of a pre-existing issue or is invalid
+
+**Note**: documentation issues don't use the `S: accepted` label currently since they're
+less likely to be rejected.
+
+## Labelling
+
+We use labels to organize, track progress, and help effectively divvy up work.
+
+Our labels are divided up into several groups identified by their prefix:
+
+- **T - Type**: the general flavor of issue / PR
+- **C - Category**: areas of concerns, ranges from bug types to project maintenance
+- **F - Formatting Area**: like C but for formatting specifically
+- **S - Status**: what stage of resolution is this issue currently in?
+- **R - Resolution**: how / why was the issue / PR resolved?
+
+We also have a few standalone labels:
+
+- **`good first issue`**: issues that are beginner-friendly (and will show up in GitHub
+  banners for first-time visitors to the repository)
+- **`help wanted`**: complex issues that need and are looking for a fair bit of work as
+  to progress (will also show up in various GitHub pages)
+- **`skip news`**: for PRs that are trivial and don't need a CHANGELOG entry (and skips
+  the CHANGELOG entry check)
+
+```{note}
+We do use labels for PRs, in particular the `skip news` label, but we aren't that
+rigorous about it. Just follow your judgement on what labels make sense for the
+specific PR (if any even make sense).
+```
+
+## Projects
+
+For more general and broad goals we use projects to track work. Some may be longterm
+projects with no true end (e.g. the "Amazing documentation" project) while others may be
+more focused and have a definite end (like the "Getting to beta" project).
+
+```{note}
+To modify GitHub Projects you need the [Write repository permission level or higher](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-access-for-each-permission-level).
+```
+
+## Closing issues
+
+Closing an issue signifies the issue has reached the end of its life, so closing issues
+should be taken with care. The following is the general recommendation for each type of
+issue. Note that these are only guidelines and if your judgement says something else
+it's totally cool to go with it instead.
+
+For most issues, closing the issue manually or automatically after a resolving PR is
+ideal. For bug reports specifically, if the bug has already been fixed, try to check in
+with the issue opener that their specific case has been resolved before closing.
+
+Design and enhancement issues should be also closed when it's clear the proposed change
+won't be implemented, whether that has been determined after a lot of discussion or just
+simply goes against _Black_'s ethos. If such an issue turns heated, closing and locking
+is acceptable if it's severe enough (although checking in with the core team is probably
+a good idea).
+
+User support issues are best closed by the author or when it's clear the issue has been
+resolved in some sort of manner.
+
+Duplicates and invalid issues should always be closed since they serve no purpose and
+add noise to an already busy issue tracker. Although be careful to make sure it's truly
+a duplicate and not just very similar before labelling and closing an issue as
+duplicate.
+
+## Common reports
+
+Some issues are frequently opened, like issues about _Black_ formatted code causing E203
+messages. Even though these issues are probably heavily duplicated, they still require
+triage sucking up valuable time from other things (although they usually skip most of
+their lifecycle since they're closed on triage).
+
+Here's some of the most common issues and also pre-made responses you can use:
+
+### "The trailing comma isn't being removed by Black!"
+
+```text
+Black used to remove the trailing comma if the expression fits in a single line, but this was changed by #826 and #1288. Now a trailing comma tells Black to always explode the expression. This change was made mostly for the cases where you _know_ a collection or whatever will grow in the future. Having it always exploded as one element per line reduces diff noise when adding elements. Before the "magic trailing comma" feature, you couldn't anticipate a collection's growth reliably since collections that fitted in one line were ruthlessly collapsed regardless of your intentions. One of Black's goals is reducing diff noise, so this was a good pragmatic change.
+
+So no, this is not a bug, but an intended feature. Anyway, [here's the documentation](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#the-magic-trailing-comma) on the "magic trailing comma". Hopefully that helps and sorry for the possible confusion.
+```
+
+### "Black formatted code is violating Flake8's E203!"
+
+```text
+Hi,
+
+This is expected behaviour, please see the documentation regarding this case (emphasis
+mine):
+
+> PEP 8 recommends to treat : in slices as a binary operator with the lowest priority, and to leave an equal amount of space on either side, **except if a parameter is omitted (e.g. ham[1 + 1 :])**. It recommends no spaces around : operators for “simple expressions” (ham[lower:upper]), and **extra space for “complex expressions” (ham[lower : upper + offset])**. **Black treats anything more than variable names as “complex” (ham[lower : upper + 1]).** It also states that for extended slices, both : operators have to have the same amount of spacing, except if a parameter is omitted (ham[1 + 1 ::]). Black enforces these rules consistently.
+
+> This behaviour may raise E203 whitespace before ':' warnings in style guide enforcement tools like Flake8. **Since E203 is not PEP 8 compliant, you should tell Flake8 to ignore these warnings**.
+
+https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#slices
+
+Have a good day!
+```
index c65cbe3c47621711865fe64357d18b8bd5a0da3c..56dbf3ffe139e738e23094c027dcaf3da49965f2 100644 (file)
@@ -1,3 +1,6 @@
+# Used by ReadTheDocs; pinned requirements for stability.
+
 MyST-Parser==0.14.0
 Sphinx==3.5.4
 sphinxcontrib-programoutput==0.17
 MyST-Parser==0.14.0
 Sphinx==3.5.4
 sphinxcontrib-programoutput==0.17
+sphinx_copybutton==0.3.1