Fully standandardizing all labels into categories

[priethor]

Based on #52583, which aimed at improving descriptions of the labels, I propose we fully follow a scoped label model similar to GitLab's, where all labels should belong to a group like type, status, etc. In WordPress words, all labels should have a [Taxonomy] Term format.

Currently, the categories for labels are:

• Type
• Status (including Need-something labels, which indicate a next step)
• Feature
• Package
• Backport (needs a follow-up action but doesn't block the issue/PR)
• Priority or difficulty related, like Good first issue
• Other categories?

By following this model, all labels would belong to a category or bucket. Standardizing them will make them more understandable and will allow for better project automation, like ensuring all PRs have one and only one Type label.

Let's discuss each category in a thread for better readability 🙏

[priethor]

Type labels

These labels should represent the kind of work. Is it a bug? Is it a feature? All issues and PRs should have one and only one of these*.

Currently, these labels include the following:

• [Type] Breaking Change
• [Type] Bug
• [Type] Build Tooling
• [Type] Code Quality
• [Type] Copy
• [Type] Developer Documentation
• [Type] Discussion
• [Type] Enhancement
• [Type] Experimental
• [Type] Feature
• [Type] Feedback
• [Type] Flaky Test
• [Type] Help Request
• [Type] New API
• [Type] Overview
• [Type] Performance
• [Type] Plugin Interoperability
• [Type] Project Management
• [Type] Question
• [Type] Regression
• [Type] Security
• [Type] Task
• [Type] Technical Prototype
• [Type] Tracking Issue
• [Type] WP Core Ticket
• Accessibility (a11y)
• Automated Testing

(*)This is something that comes up frequently when cleaning up the changelog. For example, a Bug PR should be fixing something broken in the product, affecting users/extenders, whereas fixing code in a documentation example would be documentation, and fixing an e2e test alone should be Automated testing. Or, if a PR fixes a bug but also makes the code better in the process, it is a bugfix, not a Code Quality PR.

[jordesign]

I'm not sure what the Feedback label accomplishes: isn't requesting an enhancement also feedback? Where to draw the line?

+1 to this - it's hard to know what these achieve.

• [Type] Feature - the description suggests this is related to whether it is something to flag for release notes - but I had expected it to be 'Feature Requests'

Task should be renamed to other. All issues are tasks at a high level, so the label is sometimes misused. In my opinion, it should be used for issues/PRs that don't fit in any other category.

In triaging - I used Task quite a bit when it was an issue opened by a developer working on something, kind of as a flag/reminder/todo to reference. For example: #51793

[priethor]

Thanks for the feedback, Jordan. I was primarily looking at it from a PR perspective, so it's good to hear from an issue-triaging one! However, it seems to me that the example you provided could be labeled more granularly as an enhancement; most issues are either requests or reminders, but what is task nature? A reminder to fix something or to improve/create something?

[jordesign]

That's a good point - even if a developer is treating it as a 'to do' we can style list the [type] as the kind of thing an improvement/change would be 👍

[mburridge]

It's slightly annoying that there's just one set of labels that can be applied to both Issues and PRs. Some labels that are appropriate for Issues aren't necessarily appropriate for PR's (e.g. Discussion. Feedback, Help Request, Question) and vice versa.

That said, some in the list that I'd query:

• [Type] Breaking Change - I agree this doesn't seem to be a 'type'
• [Type] Copy - not sure what this would be used for
• [Type] Discussion - not relevant to PRs, and probably also not to issues given that GitHub has a separate Discussions feature
• [Type] Feedback - not relevant to PRs
• [Type] Flaky Test - not sure that this is a 'type' either
• [Type] Help Request - not relevant to PRs
• [Type] New API - Should this be a separate 'type', isn't it just an 'Enhancement'?
• [Type] Overview - I agree this could be merged with [Type] Tracking Issue
• [Type] Question - not relevant to PRs
• [Type] Regression - I can see a case for keeping this as not all regressions are necessarily due to bugs
• [Type] Technical Prototype - Is this another one which could really come under 'Enhancement'?

To my mind, and thinking just from the perspective of PRs at the moment, these seem like the essential ones:

• Bug
• Tooling
• Code Quality
• Developer Documentation
• Enhancement
• Performance
• Security

My feeling is that there shouldn't be too many top level categories. Having just a handful will make it easier for people to decide which label to apply to their PR and so increase the chance that they will use them without some sort of enforcement being put in place.

The list above has a closer mapping to those categories used in the changelog generator and if finer gradation is needed perhaps a second tier of [sub-type] could be added.

[priethor]

It's slightly annoying that there's just one set of labels that can be applied to both Issues and PRs.

Agreed, although GH doesn't provide any way to separate both, so we need to be mindful of looking at these from both the issue and PR perspectives. We can, though, restrict to only a subset of these labels to be applied on PRs as proposed in #52760

[priethor]

Feature labels

Feature labels refer to the part of the code that is being improved/fixed/documented etc. Most issues and PRs should have one or more of these, but it is possible that some issues or PRs don't affect any feature.

[priethor]

Package labels

These are similar to the feature labels, and in a way, they overlap. All issues and PRs can have any number of these, as not all of them affect packages.

Furthermore, it is very easy to automate adding package labels to PRs based on the path of the files changed in the PR. I've been toying around with this, and can be automated easily.

[priethor]

Status labels

There are a number of Status issues disguised as "Needs something". These needs represent statutes in the workflow: for example, a Needs design issue is not actionable by a developer, and ideally PRs that need something (design feedback, a11y) should be blocked from merging.

Currently there are:

• [Status] Blocked
• [Status] Duplicate
• [Status] In discussion
• [Status] In Progress
• [Status] Needs More Info
• [Status] Not Applicable
• [Status] Not Implemented
• [Status] Stale
• Needs Accessibility Feedback
• Needs check-in
• Needs Copy Review
• Needs Decision
• Needs Design
• Needs Design Feedback
• Needs Dev
• Needs Dev Note
• Needs Figma Update
• Needs PHP backport
• Needs Technical Feedback
• Needs Testing
• Needs User Documentation
• Stale

What statuses are we missing? Which ones are redundant?

[priethor]

Some of these labels represent a closed status and their resolution, see this thread.

[priethor]

Proposal for consolidated status labels:

• [Status] Blocked
• [Status] Needs decision
• [Status] In Progress
• [Status] Needs More Info
• [Status] Stale
• [Status] Needs Accessibility Feedback
• [Status] Needs check-in
• [Status] Needs Copy Review
• [Status] Needs Design
• [Status] Needs Design Feedback
• [Status] Needs Dev
• [Status] Needs Technical Feedback
• [Status] Needs Testing

This includes:

• Moving Not applicable, not implemented, and duplicate to the resolution category.
• Moving other non-blocking Needs to the follow-up category.
• Prefixing the remaining labels with `[Status]

[jordesign]

I really like this consolidated list.

One thing i've wondered is the functional difference between 'stale' and 'needs check-in' ?

[priethor]

I recently created the Needs check-in, but it certainly isn't the best solution because it's redundant. The problem Needs check-in tries to solve is avoiding closing Stale issues that aren't actionable or need more feedback, like bug reports.

There are many types of tasks that are stale but don't need to be closed or can't be. I would be happy to remove the label and only mark issues as stale that need more info if that helps prevents the noise. What do you and other folks doing triage think?

[priethor]

Non-blocking action labels

Labels like "Needs dev note" or Backport-related ones indicate a follow-up is needed, but don't represent a status nor should be blockers (unless needing a dev note is considered a blocker to merge in the future 😉 )

[priethor]

Resolution labels

Some of the status labels represent a closed status but tell the reason why they are closed:

• [Status] Not Implemented
• [Status] Duplicate
• [Status] Not Applicable

How about creating another category called Resolution, like:

• [Resolution] Not Implemented
• [Resolution] Duplicate
• [Resolution] Not Applicable
• [Resolution] Fixed

[afercia]

Regarding the accessibility label, quoting from #54724 (comment)

I think I already pointed out in some other discussion or issue that Accessibility is typically something that spans across different areas of a project. As such, we should be able to add the Accessibility label everywhere. WhethEr it's a Type or other, I don't have strong preferences.

Accessibility in Core Trac used to be a component and was changed to Focus right for that reason. The re=organizazion of the Trac focuses dates early 2014. For more details and the reasoning about Accessibility as focus, see https://make.wordpress.org/core/2014/01/24/trac-focuses/