python/cpython labels grouping

[ezio-melotti]

There are two ways to group labels on GitHub: by color and by using a common prefix. Even though the color-coding helps, without a common prefix, labels that belong in the same category are not grouped together in the "Labels" dropdown in the sidebar. On the other hand, adding a prefix to all labels makes them longer and adds clutter.

On python/cpython, we currently have 61 labels, that include misc labels (like easy, pending, etc.) and a few main groups, including:

• types (uses the type-* prefix)
• experts (uses the expert-* prefix)
• OS (uses the OS-* prefix)
• version number (no prefix/grouping needed -- they all start with 3)
• "dir" (no prefix)

The "dir" category currently has 5 labels: stdlib, docs, tests, interpreter-core, and extension-modules, and they indicate what part of the source tree is affected, however since they have no prefix, they are not grouped. I'm not sure if dir-* would be a good prefix, but I can't think of anything better.

Another idea suggested on Discord is to use emojis as prefixes for some categories, since they only take 1 character, are easily recognizable, and can convey some semantic meaning as well.

Some suggestions:

• 📂 can be used as a prefix for the "dir" group
• 🐍 can be used as a prefix for experts
• if we want to replace the type-* prefix:
  • 📙 for crash and security, 📘 for bugs, and 📗 for feature requests
  • 🔴 🟠 🔵 🟢 / 🟥 🟧 🟦 🟩
  • 🗄️ or 🗃️ if we want the same emoji for all items
• if we want to replace the OS-* prefix: 💻 or 🖥️
• we could keep some text-based prefix, and not all labels need a prefix
• we could add prefixes to create some mini-groups:
  • ❌ for invalid/spam
  • ❗ for release blocker/deferred blocker
  • 🤖 for labels that trigger bot actions
• some bots/tools might need to be updated if we rename labels

The main goals I want to accomplish are:

• group the "dir" labels
• make related labels easier to find in the dropdown
• make label names shorter
• make the categories clearer

In addition I wanted to remove/rewrite the (already outdated) "GitHub Labels" page in the devguide and just document the categories, linking to the labels list on GitHub for the actual page and their description.

cc @Mariatta

[ezio-melotti]

We had another short discussion on Discord, here's the summary:

• people want to be able to easily search all labels of a group (e.g. expert-*)
  • replacing prefixes with emoji makes this difficult
  • adding a description that includes the name of the group makes this possible again
    • this takes more vertical space in the dropdown
    • if all labels have a description we won't have to document them in the devguide
• for accessibility, emojis should go at the end
  • for our use-case we need them at the beginning though, but that might be ok
  • emojis makes the label easier to identify, especially for people with dyslexia
  • label with a lone emojis are difficult to find in the dropdown
    • e.g. ":hammer: test-with-buildbot" is sorted under "h" (hammer) and not under "t" (test)
• single-letter label prefixes (e.g. C: * or A: *) are opaque
  • GitHub recently added label tooltips for labels with a description
    • tooltips are not too useful on mobile
• some devs prefer plain text rather than emojis
• some devs scroll and click, others search/filter and select

It seems to me that the best compromise is:

• add emoji-prefixes to keep the labels grouped and short
• add descriptions to all labels for searching/filtering/tooltips

[sobolevn]

I think that quite a lot of people in discord agree that changing expert- prefix to something like topic- is benefitial.

Right now expert- prefix might confuse new contributors by setting a difficulty level in their minds.

What do we need to do to change this? Formal vote?

[ezio-melotti]

This seems a reasonable suggestion to me.

What do we need to do to change this? Formal vote?

A discussion (possibly including a poll) on Discourse would be good both for reaching a consensus about the change (and new category name) and to advertise the change if/when it's accepted.

FWIW https://discuss.python.org/t/github-issues-migration-label-mapping/14212 has more context and previous discussions about labels and their grouping.

[sobolevn]

Done: https://discuss.python.org/t/lets-rename-expert-labels-to-something-more-welcoming/24826

[sobolevn]

The vote was open for ~1 month, it is now closed. Results:

• 70% of people voted to change the label prefix to be topic-
• 26% of people voted to keep the current prefix: expert-
• 4% of people voted to change the label prefix to be field-

CC @ezio-melotti

[hugovk]

Draft PR to update the devguide once the labels are renamed: python/devguide#1076.

Preview: https://cpython-devguide--1076.org.readthedocs.build/triage/labels/#topic-labels

[ezio-melotti]

I’ve renamed all the expert-* labels to topic-*.

These two PRs still need to be reviewed and merged:

• Remove expert-* from project-updater GH workflow cpython#103579
• Rename expert labels to topic labels devguide#1076

If you set up projects automation (using the auto-add workflow from within the project), you might have to update the workflow to use the new label, since it doesn’t seem to update automatically. The auto-add workflow is somewhat new, so I don’t expect many projects to use it.