Housekeeping: Clean-up labels

[kdeldycke]

I've been triaging issues and PRs here for more than a year.

I'd like to propose a revised taxonomy for labels that is smaller, easier to visually scan and maps cleanly to real area of expertise the Click code base is covering.

Target taxonomy

Category	Label	Color	Description	Replaces
Type	docs	#006b75	Updates to documentation, readme, docstrings, typos	(existing)
Component	parsing	#e8a44a	Parsing, parameters, commands, chaining, context	f:parser, f:chain, f:parameters, f:context, f:command
Component	shell completion	#e8a44a	Shell tab completion	f:completion
Component	help output	#e8a44a	Help text formatting, layout, and --help rendering	f:help
Component	test runner	#e8a44a	CliRunner and Click's test utilities feature	f:test runner
Component	tests	#e8a44a	Click's own test suite and CI workflows	(new, absorbs github_actions)
Component	prompt	#e8a44a	Interactive input and confirmation	f:prompt
Component	typing	#e8a44a	Type annotations and stubs	(existing)
Component	windows	#e8a44a	Windows-specific behavior	(existing)
Resolution	invalid	#cfd3d7	Spam, junk, off-topic, users learning Git in public	(existing)
Resolution	rejected AI	#cfd3d7	Contribution rejected because of its untrustworthy AI origin	(new)

Labels to create

Label	Category
tests	Component
rejected AI	Resolution

Labels to rename

Current name	New name
f:parser	parsing
f:completion	shell completion
f:help	help output
f:test runner	test runner
f:prompt	prompt

Labels to delete

Label	Reason
bug	Obvious from the title; bug tracking happens through fix milestones
TBD	"Question" status is better served by closing or converting to discussion
dependencies	Obvious from the PR title (like "update dev dependencies")
security	Vulnerabilities should be reported privately, not labeled in public
github_actions	CI work folds into tests: migrate any open issues, then delete
good first issue	Not actively used for triage
save-for-sprint	Dead process label, 0 open issues
python	Auto-created by Dependabot, never used
f:command	0 usage ever, absorbed into parsing
f:progress bar	0 open issues, all historical: migrate to rendering , then delete
f:chain	4 open issues: migrate to parsing, then delete
f:parameters	1 open issue: migrate to parsing, then delete
f:context	1 open issue: migrate to parsing, then delete

Migration plan

1. Create the new labels
2. Rename existing labels
3. Migrate open issues from labels being deleted to their new counterparts
4. Delete the old labels

Original taxonomy proposal

Category	Label	Color	Description	Replaces
Type	🐛 bug	#fbca04	Something isn't working, or a fix is proposed	bug
Type	✨ enhancement	#1d76db	New feature or improvement to an existing one	—
Type	📚 documentation	#006b75	Update to non-code (readme, docstrings, typos, ...)	docs
Type	❔ question	#d4c5f9	Further information is requested	TBD
Component	🔣 parsing	#e8a44a	Parsing, parameters, commands, chaining, context	f:parser, f:chain, f:parameters, f:context, f:command
Component	🐚 completion	#e8a44a	Shell tab completion	f:completion
Component	🖨️ rendering	#e8a44a	Help text formatting, layout, and --help output	f:help
Component	🧪 testing	#e8a44a	CliRunner and test utilities	f:test runner
Component	💬 prompt	#e8a44a	Interactive input and confirmation	f:prompt
Component	🏷️ typing	#e8a44a	Type annotations and stubs	typing
Component	🪟 windows	#e8a44a	Windows-specific behavior	windows
Resolution	🚫 wont fix	#cfd3d7	By design, or out of scope	invalid
Resolution	🧑‍🤝‍🧑 duplicate	#cfd3d7	This issue or pull request already exists	—
Resolution	🎲 can't reproduce	#cfd3d7	Bug cannot be replicated, or root cause not from project	—
Resolution	🪫 AI slop	#cfd3d7	Low-effort LLM-generated contribution	—
Operations	🚀 CI & release	#a4a837	Continuous integration, automation, release process	github_actions
Operations	🔗 dependencies	#9daf0d	Dependency changes and compatibility	dependencies
Operations	💣 security	#f83911	Security vulnerability	security

This is inspired by my own taxonomy that I'm using in my projects for a couple of years now.

[Rowlando13]

Looks good to me. I have been too good about applying tags.

[kdeldycke]

@davidism @ThiefMaster , any feedback on that?

[davidism]

A lot of my feedback is that these things should be indicated through other means rather than labels. Or that they can be found by normal search for the term in the title or body of any well written issue/pr. Overall, I'm not a big user of tags, I've tried in the past and found I'd forget to consistently apply them and could still get around fine.

I'd prefer no emoji. It feels like emoji or "feat:"/"chore"/etc prefixes in commit messages / PR titles: noisy.

I went with "docs" because it's short and it's a really common tag to apply.

Questions aren't allowed in issues, so "question" is misleading. What we're really indicating is "pending user response", which is different than "pending maintainer decision". But I tend to just close these with a message like "I can't reproduce this" for bugs; for features I haven't really run into times where I need further input to make a decision. They have two weeks to respond and add details to get it reopened, and can always open an new ticket otherwise. True questions can be converted to discussions.

I don't really use the "bug" label because typically it should be obvious from the title whether a bug or request is being reported. If it's not, edit the title to be clear (and I don't mean "feat: " prefix in title). This goes even more so for "feature", we used to have this tag and it just wasn't helpful. "bug" is sorta helpful if you remember to use it, just so you can see what needs to get done, but now I just assign it to the next fix milestone. So neither of these are really helpful.

Some tags are prefixed "f:" to indicate "feature of Click" rather than meta information about the project. Removing that, the labels need to be more specific. "test runner" is specific to the feature in Click. "testing" (or just "tests" it's shorter) seems to be about the tests themselves. For similar reasons "rendering" would probably be better as "help output" to distinguish it from color, printing, etc. "shell completion" would be more descriptive than "completion"

"duplicate" and "wontfix" are covered by the "duplicate" and "not planned" close reasons. "invalid" is not "not planned", it's for things like spam and junk and users learning git on a public repo. "can't reproduce" is covered by leaving a "I can't reproduce this with the information provided" message and closing as "not planned".

"dependencies" should be obvious from the PR title or description. I usually go with "update dev dependencies". I don't expect any other PR in this label, since we don't have dependencies.

"CI & release" is really two things. "CI" is the the other side of the ambiguous "testing" tag I talked about earlier, and I'd rather use "tests" than "CI". The "release" tag would only be used on the "release a.b.c" titled issue and PR, which are essentially already tagged by their title.

"security" should never be used, as it should be reported privately. If it's not reported privately, it doesn't matter if it's tagged, it's just a public bug at that point (and should then be written as such).

As described earlier, use "invalid" instead of "AI slop". There are multiple reasons something is junk/spam/invalid. I'm fine with adding "rejected AI" or something a little more encompassing and clear, "slop" is always a bit of a judgement call and often the problem isn't outright slop being generated but just the inherent untrustworthy origin.

[davidism]

I guess to follow up on the first paragraph: a huge number of labels can be useful, but only if we have everyone/someone keeping everything tagged consistently. Otherwise, they need to be for the most important things only, to make things stand out among other unlabeled tickets.

[kdeldycke]

A lot of my feedback is that these things should be indicated through other means rather than labels. Or that they can be found by normal search for the term in the title or body of any well written issue/pr. Overall, I'm not a big user of tags, I've tried in the past and found I'd forget to consistently apply them and could still get around fine.

One reason to use tag is to roughly assign an issue or PR to an area of expertise. Which is great for multi-maintainer projects like Click: it's easier for them to pick up stuff.

I'd prefer no emoji. It feels like emoji or "feat:"/"chore"/etc prefixes in commit messages / PR titles: noisy.

Definitely a matter of preference. I am using emoji in labels since 2020 in my project as they provide quick visual identification. And it has been a great time saver.

But could be a source of bike-shedding in Click. So let's forget about them and stick to the traditional text labels.

I went with "docs" because it's short and it's a really common tag to apply.

Questions aren't allowed in issues, so "question" is misleading. What we're really indicating is "pending user response", which is different than "pending maintainer decision". But I tend to just close these with a message like "I can't reproduce this" for bugs; for features I haven't really run into times where I need further input to make a decision. They have two weeks to respond and add details to get it reopened, and can always open an new ticket otherwise. True questions can be converted to discussions.

I don't really use the "bug" label because typically it should be obvious from the title whether a bug or request is being reported. If it's not, edit the title to be clear (and I don't mean "feat: " prefix in title). This goes even more so for "feature", we used to have this tag and it just wasn't helpful. "bug" is sorta helpful if you remember to use it, just so you can see what needs to get done, but now I just assign it to the next fix milestone. So neither of these are really helpful.

Some tags are prefixed "f:" to indicate "feature of Click" rather than meta information about the project. Removing that, the labels need to be more specific. "test runner" is specific to the feature in Click. "testing" (or just "tests" it's shorter) seems to be about the tests themselves. For similar reasons "rendering" would probably be better as "help output" to distinguish it from color, printing, etc. "shell completion" would be more descriptive than "completion"

"duplicate" and "wontfix" are covered by the "duplicate" and "not planned" close reasons. "invalid" is not "not planned", it's for things like spam and junk and users learning git on a public repo. "can't reproduce" is covered by leaving a "I can't reproduce this with the information provided" message and closing as "not planned".

"dependencies" should be obvious from the PR title or description. I usually go with "update dev dependencies". I don't expect any other PR in this label, since we don't have dependencies.

"CI & release" is really two things. "CI" is the the other side of the ambiguous "testing" tag I talked about earlier, and I'd rather use "tests" than "CI". The "release" tag would only be used on the "release a.b.c" titled issue and PR, which are essentially already tagged by their title.

"security" should never be used, as it should be reported privately. If it's not reported privately, it doesn't matter if it's tagged, it's just a public bug at that point (and should then be written as such).

As described earlier, use "invalid" instead of "AI slop". There are multiple reasons something is junk/spam/invalid. I'm fine with adding "rejected AI" or something a little more encompassing and clear, "slop" is always a bit of a judgement call and often the problem isn't outright slop being generated but just the inherent untrustworthy origin.

I will now take all your label feedback, integrate them and update my initial plan.

[kdeldycke]

I guess to follow up on the first paragraph: a huge number of labels can be useful, but only if we have everyone/someone keeping everything tagged consistently. Otherwise, they need to be for the most important things only, to make things stand out among other unlabeled tickets.

I guess I'll be the one adding up the labels! 😅 Labels helps me navigate a release: if a lot of issues tackle one domain in particular, like completion, and I don't see a lot of references to completion-like documentation or changelog before a release, it will hint me that something is fishy and I need to re-review the whole accumulated changes over that area.

Another thing on my mind: maybe with proper label I can make some graphs of activity. And demonstrate how low-efforts AI PRs have invaded our backlog. That would be a great slide for PyCon! 😁

[kdeldycke]

Just updated the target taxonomy with @davidism's feedback. Waiting for another set of review or final approval before applying the migration plan.