Proposal: replace our 111 labels with ~20 plain tags

[oxarbitrage]

TL;DR

Our label system has decayed: 111 labels, of which 20 have never been used, 21 are dormant, and at least 6 are duplicates of each other. More importantly, we don't apply them: 30% of open issues and ~60% of recently merged PRs carry no labels at all, priority labels cover 11% of the backlog (with P-Critical on zero open items), and S-needs-triage is a 49-deep queue whose oldest member is from 2022.

I propose we delete ~86 labels and replace the prefix families (A-, C-, P-, S-, I-, NU-) with a small set of plain-English tags, bitcoin-core-style. The full audit data and migration plan are below.

Why bother

• Filters lie today. "All open network bugs" misses most of them — coverage is too spotty and concepts are split across duplicate names (C-documentation vs A-docs, C-enhancement vs C-feature vs C-suggestion).
• Labeling is too expensive, so we skip it. Choosing from 111 fuzzy options costs real thought per issue. One of 4 types + one of 6 areas takes seconds. Small vocabularies survive because they're effortless — this is what reth and bitcoin converged on; zcash/zcash (233 labels, ~60 alive) is the cautionary tale we're currently following.
• Priority is noise. The live backlog skews P-Low/P-Optional while P-Critical sits unused — the opposite of what a priority signal should look like.
• Machine switches masquerade as taxonomy. C-benchmark looks like a category but triggers a workflow; S-ci-fail-* look like statuses but are bot dedup keys. Touching the wrong label can start or cancel a multi-hour GCP run.

The proposed set — 20 human labels

Dimension	Labels	Rule
Type (4)	bug · enhancement · docs · security	every issue gets exactly one at triage
Area (6)	consensus · network · state · rpc · devops · tests	every issue gets at least one at triage
Priority (1)	urgent	means "jumps the merge queue today"; absence = normal
Flow (3)	triage · blocked · tracking	blocked requires a comment saying blocked-on-what
Community (2)	good first issue · help wanted	GitHub-native names → free UI treatment
Process (4)	do-not-merge · run-stateful-tests · release · skip-changelog	machine switches, never repurposed

Plus a few near-machine labels humans rarely touch: dependencies, benchmark, extra-reviews, external-contribution, and a rolling nu-7 (one label per active network upgrade, deleted ~2 releases after activation). Five ci-fail-* labels remain as bot-only dedup keys on auto-filed CI issues.

Notable deletions: the entire I- impact family (18 labels — severity moves into issue text; security covers the sharp end), the 5-level P- family (collapses to urgent), all historic NU labels (Genesis through NU-6.1), and every duplicate/stray.

Severity-out-of-labels is the biggest philosophical change — it's how bitcoin core operates, and our data says the I- family was applied to ~10% of issues anyway, so filtering on it was never reliable.

What the automation audit found (the careful part)

I audited every label reference in our automation before proposing this. The exact-name dependencies:

• A-release is wired into five systems (pr-gate, tests-unit's check-no-git-dependencies, release.yml's validation, .release-plz.toml which auto-applies it, checkpoint-update) — and failures are silent (if: conditions just go false). Renaming it to release requires one atomic PR touching all of them, tested on a fork first. If the release owners prefer zero risk here, keeping A-release as the single legacy name is a fine fallback — please weigh in.
• Mergify matches priorities by prefix regex (^P-Critical, ^P-(Optional|Low)). Plan: urgent replaces the critical rule, and the low-priority rule switches to author~=dependabot — which is what frees us to delete the whole P- family.
• Dependabot, benchmarks.yml, the GCP stateful-test trigger, 7 issue templates, and the ci-fail-* dedup keys all get updated in the same PR. Branch-protection rulesets key on check names, not labels — no risk there.
• Timing guard: bulk relabeling fires labeled events, and the GCP workflow lacks the fix(ci): stop Mergify label events from cancelling required PR Gate runs #11164 concurrency protection — we'll run any backlog migration when no stateful runs are in flight.

Migration plan

1. This discussion — one week for comments; release-pipeline owners explicitly sign off on (or veto) the A-release rename.
2. Free deletions (~55 labels with no automation references and dead usage) — no code changes, trivially reversible.
3. Renames (C-bug→bug, A-consensus→consensus, ...) — GitHub renames preserve attachments, so existing issues inherit the new names. Every survivor gets a one-line description. The issue templates and the Mergify/dependabot priority rules must be updated in the same window (templates silently skip nonexistent labels; the P- deletion needs Mergify keying on author~=dependabot first) — that's a small, low-risk PR.
4. Optional: machine-label renames (A-release→release, C-benchmark→benchmark, S-ci-fail-*→ci-fail-*) — one atomic PR, fork-tested. Skippable entirely: keeping the legacy names costs us a handful of prefixed stragglers and nothing else.
5. Optional: backlog sweep — relabel the 322 open issues (95 currently unlabeled) and drain the 49-item triage queue. The new system works going forward without this; doing it doubles as a long-overdue backlog scrub. Can happen anytime, in batches.
6. Keep it alive — labeling rules land in the dev book; a 15-minute label audit joins the quarterly routine. The core rule: an issue gets one type + one area at triage — everything else is exceptional.

Questions for the team

1. Any objection to dropping the prefix families entirely?
2. Release owners: rename A-release → release (atomic PR, fork-tested), or keep the legacy name?
3. Anyone attached to the I- severity family — any filter/report you actually run on it?
4. Is 6 areas the right granularity, or does anyone want a 7th (e.g. splitting mempool out of state)?

If there are no blocking objections in a week, we can start with step 2, which is trivially reversible.

[conradoplg]

I like it

Renaming A-release should be fine as long as we carefully coordinate it.

[alchemydc]

Agreed. We fixed an issue friday re: a Mergify / label interaction. I think the plan captures the impact of changing the A-release but pls double check as part of implementation.

[mpguerra]

I agree with this proposal. There's a couple of extra things we should take into account if we want to assign priorities to issues on our backlog:

• issues on the Engineering project board are already ordered by priority so the label does not really help
• if we wanted to label issues anyway we can use a custom project fields which you can also sort on if necessary

For the "type" label, github already has some type fields and you can add extra ones

The "Flow" section, might overlap with the Engineering board and how we use various different columns but I will let @natalieesk comment on this one

[natalieesk]

Yes, I think the only "type" labels we need are 'security' and maybe 'docs'. But I don't know if 'docs' actually provides us with any value in knowing that. If we have a smaller backlog (the goal) then it will just get triaged appropriately. I don't know if that label provides value.

[natalieesk]

With regards to the "Flow" section:

1. Triage - We don't need this. Everything goes through triage on a regular basis. (Another reason it's important to keep the board up to date)
2. Blocked - This is a must and is very useful. Completely agree that there needs to be a comment explaining why it's blocked.
3. Tracking - I'm not that keen on tracking issues and think we should stop them all together. I think we should stick to Epics where it makes sense and everything else should have it's own issue. Keeping the 1:1 PR:Issue ratio is important for communication and tracking. Tracking issues without a PR to close them just get lost. If something is getting significantly big, then it should just be split up.

[natalieesk]

1. Absolutely yes to dropping the prefixes. They're unnecessary.

[natalieesk]

It is important that we use labels properly. When creating issues, the prompts we're using (which we should all use) can mostly identify the correct labels which reduces friction. I will update our existing prompts with the new labels once we've made this decision.

[natalieesk]

I think for Migration point 6, we should be assessing all labels at triage with the help of AI when we're using it. If we don't do it then, then we probably won't do it. Of course anything that is unknowable then will be addressed as and when needed.

[natalieesk]

We also need a 'needs-issue' label. This is being used for automating issue creation from an existing PR.

[natalieesk]

For Area - do people find these useful? "devops" is definitely required, but what do the other labels add to the issue? Do they help people decide what to pick up? Are they for us or external people? Are they useful for filtering?

Let's think about what the labels are there to achieve - what is the value they are adding or problem they are solving.

[natalieesk]

I would err on the side of less labels and adding them back in if we feel something is missing or needed. So, if we're not sure we need something, it goes.

[natalieesk]

I think we should also maintain the same labels across all repos. So, 'security', 'external' etc.

[natalieesk]

We have some issues which can probably just be completed by AI because they're very simple. We'll still review them of course. Should we add a label for that too?