docs/contributing/issue_triage.md

   1 # Issue triage
   2
   3 Currently, _Black_ uses the issue tracker for bugs, feature requests, proposed design
   4 modifications, and general user support. Each of these issues have to be triaged so they
   5 can be eventually be resolved somehow. This document outlines the triaging process and
   6 also the current guidelines and recommendations.
   7
   8 ```{tip}
   9 If you're looking for a way to contribute without submitting patches, this might be
  10 the area for you. Since _Black_ is a popular project, its issue tracker is quite busy
  11 and always needs more attention than is available. While triage isn't the most
  12 glamorous or technically challenging form of contribution, it's still important.
  13 For example, we would love to know whether that old bug report is still reproducible!
  14
  15 You can get easily started by reading over this document and then responding to issues.
  16
  17 If you contribute enough and have stayed for a long enough time, you may even be
  18 given Triage permissions!
  19 ```
  20
  21 ## The basics
  22
  23 _Black_ gets a whole bunch of different issues, they range from bug reports to user
  24 support issues. To triage is to identify, organize, and kickstart the issue's journey
  25 through its lifecycle to resolution.
  26
  27 More specifically, to triage an issue means to:
  28
  29 - identify what type and categories the issue falls under
  30 - confirm bugs
  31 - ask questions / for further information if necessary
  32 - link related issues
  33 - provide the first initial feedback / support
  34
  35 Note that triage is typically the first response to an issue, so don't fret if the issue
  36 doesn't make much progress after initial triage. The main goal of triaging to prepare
  37 the issue for future more specific development or discussion, so _eventually_ it will be
  38 resolved.
  39
  40 The lifecycle of a bug report or user support issue typically goes something like this:
  41
  42 1. _the issue is waiting for triage_
  43 2. **identified** - has been marked with a type label and other relevant labels, more
  44    details or a functional reproduction may be still needed (and therefore should be
  45    marked with `S: needs repro` or `S: awaiting reponse`)
  46 3. **confirmed** - the issue can reproduced and necessary details have been provided
  47 4. **discussion** - initial triage has been done and now the general details on how the
  48    issue should be best resolved are being hashed out
  49 5. **awaiting fix** - no further discussion on the issue is necessary and a resolving PR
  50    is the next step
  51 6. **closed** - the issue has been resolved, reasons include:
  52    - the issue couldn't be reproduced
  53    - the issue has been fixed
  54    - duplicate of another pre-existing issue or is invalid
  55
  56 For enhancement, documentation, and design issues, the lifecycle looks very similar but
  57 the details are different:
  58
  59 1. _the issue is waiting for triage_
  60 2. **identified** - has been marked with a type label and other relevant labels
  61 3. **discussion** - the merits of the suggested changes are currently being discussed, a
  62    PR would be acceptable but would be at sigificant risk of being rejected
  63 4. **accepted & awaiting PR** - it's been determined the suggested changes are OK and a
  64    PR would be welcomed (`S: accepted`)
  65 5. **closed**: - the issue has been resolved, reasons include:
  66    - the suggested changes were implemented
  67    - it was rejected (due to technical concerns, ethos conflicts, etc.)
  68    - duplicate of a pre-existing issue or is invalid
  69
  70 **Note**: documentation issues don't use the `S: accepted` label currently since they're
  71 less likely to be rejected.
  72
  73 ## Labelling
  74
  75 We use labels to organize, track progress, and help effectively divvy up work.
  76
  77 Our labels are divided up into several groups identified by their prefix:
  78
  79 - **T - Type**: the general flavor of issue / PR
  80 - **C - Category**: areas of concerns, ranges from bug types to project maintenance
  81 - **F - Formatting Area**: like C but for formatting specifically
  82 - **S - Status**: what stage of resolution is this issue currently in?
  83 - **R - Resolution**: how / why was the issue / PR resolved?
  84
  85 We also have a few standalone labels:
  86
  87 - **`good first issue`**: issues that are beginner-friendly (and will show up in GitHub
  88   banners for first-time visitors to the repository)
  89 - **`help wanted`**: complex issues that need and are looking for a fair bit of work as
  90   to progress (will also show up in various GitHub pages)
  91 - **`skip news`**: for PRs that are trivial and don't need a CHANGELOG entry (and skips
  92   the CHANGELOG entry check)
  93
  94 ```{note}
  95 We do use labels for PRs, in particular the `skip news` label, but we aren't that
  96 rigorous about it. Just follow your judgement on what labels make sense for the
  97 specific PR (if any even make sense).
  98 ```
  99
 100 ## Projects
 101
 102 For more general and broad goals we use projects to track work. Some may be longterm
 103 projects with no true end (e.g. the "Amazing documentation" project) while others may be
 104 more focused and have a definite end (like the "Getting to beta" project).
 105
 106 ```{note}
 107 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).
 108 ```
 109
 110 ## Closing issues
 111
 112 Closing an issue signifies the issue has reached the end of its life, so closing issues
 113 should be taken with care. The following is the general recommendation for each type of
 114 issue. Note that these are only guidelines and if your judgement says something else
 115 it's totally cool to go with it instead.
 116
 117 For most issues, closing the issue manually or automatically after a resolving PR is
 118 ideal. For bug reports specifically, if the bug has already been fixed, try to check in
 119 with the issue opener that their specific case has been resolved before closing. Note
 120 that we close issues as soon as they're fixed in the `main` branch. This doesn't
 121 necessarily mean they've been released yet.
 122
 123 Design and enhancement issues should be also closed when it's clear the proposed change
 124 won't be implemented, whether that has been determined after a lot of discussion or just
 125 simply goes against _Black_'s ethos. If such an issue turns heated, closing and locking
 126 is acceptable if it's severe enough (although checking in with the core team is probably
 127 a good idea).
 128
 129 User support issues are best closed by the author or when it's clear the issue has been
 130 resolved in some sort of manner.
 131
 132 Duplicates and invalid issues should always be closed since they serve no purpose and
 133 add noise to an already busy issue tracker. Although be careful to make sure it's truly
 134 a duplicate and not just very similar before labelling and closing an issue as
 135 duplicate.
 136
 137 ## Common reports
 138
 139 Some issues are frequently opened, like issues about _Black_ formatted code causing E203
 140 messages. Even though these issues are probably heavily duplicated, they still require
 141 triage sucking up valuable time from other things (although they usually skip most of
 142 their lifecycle since they're closed on triage).
 143
 144 Here's some of the most common issues and also pre-made responses you can use:
 145
 146 ### "The trailing comma isn't being removed by Black!"
 147
 148 ```text
 149 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.
 150
 151 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", including the ability to skip this functionality with the `--skip-magic-trailing-comma` option. Hopefully that helps solve the possible confusion.
 152 ```
 153
 154 ### "Black formatted code is violating Flake8's E203!"
 155
 156 ```text
 157 Hi,
 158
 159 This is expected behaviour, please see the documentation regarding this case (emphasis
 160 mine):
 161
 162 > 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.
 163
 164 > 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**.
 165
 166 https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#slices
 167
 168 Have a good day!
 169 ```