Meta task: ensure all labels have descriptions to improve triage efforts

[annezazu]

Right now, we have over 300 labels in this GitHub repo with many missing descriptions. This makes triaging efforts tricky to accomplish across a wider group of people when the labels could be used in different ways. To help standardize and make triaging more accurate, let's add descriptions and consider deprecating labels for no longer active projects (like the block based navigation screen).

As a start, I've added proposed descriptions for each label into this spreadsheet created by @jordesign. If anyone on the @WordPress/gutenberg-triage-team would like to help, feel free to jump in with comments and suggestions.

• Create initial descriptions for all labels.
• Review and edit descriptions for clarity, accuracy, and consistency.
• Update descriptions of all labels.
• Remove or consolidate any unused labels.

[annezazu]

Notes on likely labels to consolidate and/or remove pulled from the sheet itself but shared here for transparency:

• Consolidate Full Site Editing Label into Site Editor due to this change.
• Update "Feature: Reusable blocks" label to "[Feature] Synced Patterns (former reusable blocks)" or edit it in the description. Might make sense to consider consolidating fully into "Feature: Patterns" in the future.
• Remove "[Feature] Navigation Screen"

@alexstine I know you've mentioned consolidating the accessibility labels. Curious if this might be the best time to do so!

[bph]

cc @ndiego

[fabiankaegy]

Looking through some of the initial suggestions, I'd like to clarify something. Instead of describing the functionality of the element described in the label, the descrition here should explain what it means for this label to be applied.

And in the case of all the [Block] labels for example that means that the issue is affecting that particular block in the block library.

So there should be one [Block] Block Name label for every one of the blocks in the block library with a description saying something like. Used to indicate that the ticket affects the XXX block

(Just my initial thoughts :))

[priethor]

I'd also suggest consolidating Overview and Tracking issues into something like [Type] High-level issue: while there is a slight difference in both, they are often used indistinctly, and in practice, one has to search for both labels to find the high-level issues.

Another suggestion would be to consolidate the Backport to Gutenberg RC and Backport to Gutenberg Minor Release into a single one. The reason is twofold: with such fast release cycles, it's common that a PR tagged as backport to RC is finished after GB is released, and it then needs to be backported to a minor release instead. So, depending on the week, only one of both labels is used.

[bph]

There was a discussion release squad channel regarding the wording "Backport to WordPress Beta/RC " is not entirely accurate and a tad misleading and while we are at it we could rename those label to accurately

[bph]

As long as the work is done in a spreadsheet, it would be great if we could add a "changelog" column to it, and identify the Changelog heading under which labels should fall (if at all) so that the automatic changelog creation for the release process can also be updated after this audit work.

[alexstine]

@annezazu Thanks for the ping.

As far as accessibility labels go, we have way too many of them all from the Gutenberg audit back in 2017/2018. I suggest making them much simpler.

1. Accessibility: Anything that fixes or improves accessibility. Bugs, enhancements, etc.
2. Needs Accessibility Feedback: Anything that you need the Accessibility Team to actively review.

CC: @joedolson @afercia

[joedolson]

I agree. The profusion of accessibility labels makes it more difficult to do bug scrubs, and I'm not clear that there's any benefit to separating keyboard issues from labeling issues, for example. That should always be clear from the issue description.

[femkreations]

Building upon what @fabiankaegy said. It will be super helpful to have a label for every block and add labels to issues based on which blocks are affected by the ticket. This will help the Docs team immensely when we do triage for every release.

[fabiankaegy]

@femkreations The labels for this have existed for quite a while already: https://github.com/WordPress/gutenberg/labels?q=%5BBlock%5D I think most if not all should be there and I think they are getting used quite a bit.

[jordesign]

Just looping back to this to keep things moving - I'll consolidate the changes proposed/discussed so far:

Confirmed

• Consolidate Full Site Editing Label into Site Editor due to this change.
• Update "Feature: Reusable blocks" label to "[Feature] Synced Patterns (former reusable blocks)" or edit it in the description. Might make sense to consider consolidating fully into "Feature: Patterns" in the future.
• Remove "[Feature] Navigation Screen"
• Consolidate all [a11y] labels to Accessibility and Needs Accessibility Feedback labels
• Confirm we have a [blocks] label for all blocks

Needs Discussion

I'd also suggest consolidating Overview and Tracking issues into something like [Type] High-level issue: while there is a slight difference in both, they are often used indistinctly, and in practice, one has to search for both labels to find the high-level issues.

Should we make a change like this?

Another suggestion would be to consolidate the Backport to Gutenberg RC and Backport to Gutenberg Minor Release into a single one.

@bph @priethor do you have any further thoughts on a resolution to this one?

[jordesign]

Another thought while we are considering labels. I wonder if there is an opportunity to better indicate the 'Next step' for issues to see how actionable they are?

At the moment we have something like that with the [status] labels and also various [Needs X] labels - but i wonder if there is value to consolidating and formalising those?

[afercia]

As far as accessibility labels go, we have way too many of them all from the Gutenberg audit back in 2017/2018. I suggest making them much simpler.

Thanks for the ping @alexstine .
I'd totally agree. Sometimes I myself was a bit in a struggle when having to mark an issue as general accessibility or only a11y labeling, keyboard and focus, etc. Also, marking an issue, for example, with only a11y labeling may make people miss it when they search for general accessibility.
@annezazu I'd totally second Alex's suggestion to reduce at only two a11y labels.

A different matter is about pull requests. In the last months I spotted several PRs that introduced changes where no keyboard testing was performed at all. Or where screen reader testing was necessary but was no performed at all. I'd like to find a way to enforce this kind of testing when necessary but I'm not sure labels are the best option.

[mrfoxtalbot]

Thank you for consolidating the conversation so far, @jordesign.

we have something like that with the [status] labels and also various [Needs X] labels - but i wonder if there is value to consolidating and formalising those?

That's interesting, @jordesign. I feel that there is a clear overlap between [Status] and [Needs X] labels.

In fact, there is a label literally called [Status] Needs More Info which includes both words.

One quick-ish approach would be to prefix all the current Needs X labels with [Status] to draw attention to the fact that they have a very similar use. So, for instance Needs Design would become [Status] Needs Design but I do not know how everyone uses those labels and there might be good reasons to leave it the way it is.

Two more ideas:

• [Status] Duplicate does not seem very useful since we tend to cross-reference and close duplicates immediately. In fact it is only assigned to two issues.
• [Status] Not Implemented only has one issue assigned to it and the name of the label is not too clear (Issue/PR we will (likely) not implement.). At the same time, I have heard a number of times that it would be useful to be able to make a distinction between enhancements that are likely to be added and those that are not. I would propose we give this label a clearer name ([Status] Maybelater?) and use it to tag enhancements, or even bugs, that are unlikely to be addressed.

[priethor]

Another suggestion would be to consolidate the Backport to Gutenberg RC and Backport to Gutenberg Minor Release into a single one.

@bph @priethor do you have any further thoughts on a resolution to this one?

I would just rename them to Backport to latest release branch. I created both labels to experiment and after being involved using them regularly, I don't see any downside to renaming them 🙂

[priethor]

Since this issue is primarily aimed at improving label descriptions and In the spirit of maintaining an organized discussion, I've spun off a discussion in #52727 for a deeper label reorganization to avoid moving this issue forward.

I've divided the discussion into a thread for each kind of label (status, type, etc.) so that the conversation is easier to follow. Feel free to add more threads 🙏

[jordesign]

And in the case of all the [Block] labels for example that means that the issue is affecting that particular block in the block library.
So there should be one [Block] Block Name label for every one of the blocks in the block library with a description saying something like. Used to indicate that the ticket affects the XXX block

I've updated the spreadsheet so that all labels related to [Block] have a description in the form Affects [block-name] Block. For some I've included some additional information to explain what the block does if it isn't clear from the name.

[jordesign]

This is all looking good to me. Unless there’s a reason against it - I’m happy to start making these changes this time tomorrow.

[annezazu]

Catching back up here. Deeply appreciate the discussion and diving in. Let's proceed with adding descriptions. @jordesign please do the honors before we can proceed to deletion/consolidation.

The biggest item I'm concerned about is deleting/consolidating labels as deleting a label will remove it from the issue/PR. Here's what I am seeing to do:

• For the navigation screen label, let's close those issues out.
• For accessibility in particular, we need to ensure that any issue with a label we remove (ex: color contrast, keyboard, etc) then has either Accessibility or Needs Accessibility Feedback added. I can handle this unless someone else wants to. I will likely just mass apply Accessibility before more granularly adding in Needs Accessibility Feedback since that's more likely less used.
• For Full Site Editing label (186 items), we need to change to Site Editor or another more granular option. I can handle this unless someone else wants to. I'll likely just mass apply Site Editor then review them slowly in the coming weeks.

Note for self and others: also need to ensure we check PRs not just issues :)

What do you all think of the above? Any concerns/questions? I'll give it another week before following up.

[jordesign]

Let's proceed with adding descriptions

Done! 🥳 All descriptions for labels now added/updated

[afercia]

For accessibility in particular, we need to ensure that any issue with a label we remove (ex: color contrast, keyboard, etc) then has either Accessibility or Needs Accessibility Feedback added. I can handle this unless someone else wants to. ...

Please do feel free to go ahead and thank you!

[annezazu]

Rad, I'll follow up next week to handle removing/consolidating (unless someone else wants to take it on) :)

[priethor]

Hi all! I went forward and consolidated into Accessibility (a11y), including updating all open and closed issues and PRs, the following labels:

• [a11y] Color Contrast
• [a11y] Epic
• [a11y] Keyboard & Focus
• [a11y] Labelling
• [a11y] Zooming

[annezazu]

Update on my end to close this out:

• Marked all Full Site Editing issues/PRs as Site Editor and deleted the Full Site Editing label. This included two PRs.
• Updated "Feature: Reusable blocks" label to "[Feature] Synced Patterns" after confirming the description lists "reusable blocks"
• I couldn't find "[Feature] Navigation Screen" so let's consider this closed out.

Thanks so much, folks, for diving in and moving this forward. Love the quick work and collaboration. In the coming weeks, I'll try to get more granular around the 350+ Site Editor items, although I found many had additional labels already :)