Skip to content

Commit

Permalink
Update triage docs for clarity around closing issues and labels (#26480)
Browse files Browse the repository at this point in the history
Inspired by @mkaz reference to https://github.com/microsoft/vscode/wiki/Issue-Grooming in a recent core-editor meeting, I put the labels into tables, separated out the priority section for clarity mainly to make sure that only those with expertise are determining priority labels, and included a section on why issues are closed. Feedback welcome on it all!
  • Loading branch information
annezazu committed Oct 26, 2020
1 parent 28cdde9 commit 8990676
Showing 1 changed file with 33 additions and 10 deletions.
43 changes: 33 additions & 10 deletions docs/contributors/triage.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,6 @@ When triaging, either one of the lists above or issues in general, work through

* First search for duplicates. If the issue is duplicate, close it by commenting with “Duplicate of #” and add any relevant new details to the existing issue. (Don’t forget to search for duplicates among closed issues as well!).
* If the issue is missing labels, add some to better categorize it (requires proper permissions given after joining the triage team). A good starting place when adding labels is to apply one of the labels prefixed [Type] (e.g. [Type] Enhancement or [Type] Bug) to indicate what kind of issue it is. After that consider adding more descriptive labels. If the issue concerns a particular core block, add one of the labels prefixed [Block]. Or if the issue affects a particular feature there are [Feature] labels. Finally, there are labels that affect particular interest areas, like Accessibility and Internationalization. You can view all possible labels [here](https://github.com/WordPress/gutenberg/labels).
* Consider adding priority if you can confidently determine what the likely level should be:
* Priority OMGWTFBBQ: Major issues that are causing failures and are reported frequently. Typically, these are issues that are critical because they break important behaviour or functionality. An example might be, “Unable to remove a block after it is added to the editor”.
* Priority: High: Fits one of the current focuses and is causing a major broken experience (including flow, visual bugs and blocks).
* Priority: Low: Enhancements that aren’t part of focuses, iche bugs, problems with old browsers.
* Note that it’s on purpose that no priority label infers a normal level.
* If the title doesn’t communicate the issue clearly enough, edit it for clarity (requires proper permissions). Specifically, we’d recommend having the main feature the issue relates to in the beginning of the title ([example](https://github.com/WordPress/gutenberg/issues/6193)) and for the title to generally be as succinct yet descriptive as possible ([example](https://github.com/WordPress/gutenberg/issues/6193)).
* If it’s a bug report, test to confirm the report or add the Needs Testing label. If there is not enough information to confirm the report, add the [Status] Needs More Info label and ask for the details needed. It’s particularly beneficial when a bug report has steps for reproduction so ask the reporter to add those if they’re missing.
* Remove the [Status] Needs More Info if the author of the issue has responded with enough details.
Expand All @@ -47,12 +42,40 @@ When triaging, either one of the lists above or issues in general, work through
* Check that the bug report is valid by debugging it to see if you can track down the technical specifics.
* Check if the issue is missing some detail and see if you can fill in those details. For instance, if a bug report is missing visual detail, it’s helpful to reproduce the issue locally and upload a screenshot or GIF.
* Consider adding the Good First Issue label if you believe this is a relatively easy issue for a first-time contributor to try to solve.

**Commonly Used Labels**

Generally speaking, the following labels are very useful for triaging issues and will likely be the ones you use the most consistently:
* Needs Technical Feedback - when you see new features or API changes proposed.
* Needs More Info - when it’s not clear what the issue is or it would help to provide additional details.
* Needs Testing - when old bugs seem like they are no longer relevant.
* [Type] Help Request - when someone is asking for general help with setup/implementation.
Generally speaking, the following labels are very useful for triaging issues and will likely be the ones you use the most consistently. You can view all possible labels [here](https://github.com/WordPress/gutenberg/labels).

| Label | Reason |
| ------------- | ------------- |
|`[Type] Bug` | When an intended feature is broken. |
|`[Type] Enhancement` | When someone is suggesting an enhancement to a current feature. |
| `[Type] Help Request` | When someone is asking for general help with setup/implementation. |
| `Needs Technical Feedback` | When you see new features or API changes proposed. |
| `Needs More Info` | When it’s not clear what the issue is or it would help to provide additional details. |
| `Needs Testing` | When a new issue needs to be confirmed or old bugs seem like they are no longer relevant. |

**Determining Priority Labels**

If you have enough knowledge about the report at hand and feel confident in doing so, you can consider adding priority. Note that it’s on purpose that no priority label infers a normal level.

| Label | Reason |
| ------------- | ------------- |
|`Priority OMGWTFBBQ` | Major issues that are causing failures and are reported frequently. Typically, these are issues that are critical because they break important behaviour or functionality. An example might be, “Unable to remove a block after it is added to the editor”. |
|`Priority: High` | Fits one of the current focuses and is causing a major broken experience (including flow, visual bugs and blocks). |
| `Priority: Low` | Enhancements that aren’t part of focuses, iche bugs, problems with old browsers. |

### Closing issues

Issues are closed for the following reasons:

* A PR and/or latest release resolved the reported issue.
* Duplicate of a current report.
* Help request that is best handled in the WordPress.org forums.
* An issue that's not able to be replicated.
* An issue that needs more information that the author of the issue hasn't responded to for 2+ weeks.
* An item that is determined as unable to be fixed or is working as intended.

### Release specific triage
Here are some guidelines to follow when doing triage specifically around the time of a release. This is important to differentiate compared to general triage so problematic, release blocking bugs are properly identified and solutions are found.
Expand Down

0 comments on commit 8990676

Please sign in to comment.