Repo governance: label taxonomy, triage workflow, and PR lifecycle #690
Description
Context
The project has grown significantly but our issue/PR management hasn't kept up. Right now:
- 20 open issues have no labels (25% of total)
- 25 non-draft open PRs have no labels (65% of contributor PRs)
- No priority system exists
- No PR lifecycle labels (stale, do-not-merge, ready-to-merge)
- No triage workflow defined
enhancementcarries 36 issues alone without differentiating a one-line tweak from a full rewrite- 7 labels have never been used (
duplicate,invalid,question,wontfix,launch,hooks,exceptions) - PRs from 2024 sit open with no activity or status indication
This umbrella issue tracks the work to establish a structured label taxonomy, define triage and PR lifecycle workflows, and migrate existing issues/PRs to the new system.
Proposed Label Taxonomy
Convention: prefix/value (scannable, filterable, consistent)
kind/ — What it is (required on every issue and PR)
| Label | Color | Replaces | When to use |
|---|---|---|---|
kind/bug |
#d73a4a |
bug |
Something is broken |
kind/feature |
#a2eeef |
enhancement (new) |
Net-new functionality |
kind/improvement |
#7fd4f2 |
enhancement (existing) |
Improving something that already exists |
kind/documentation |
#0075ca |
documentation |
Docs, examples, notebooks |
kind/cleanup |
#e6e6e6 |
repo hygiene |
Refactor, typos, tech debt |
kind/question |
#d876e3 |
question |
Usage questions |
kind/umbrella |
#50645A |
umbrella |
Tracking issue grouping sub-issues |
area/ — Where in the codebase (at least 1 per issue/PR)
| Label | Color | Replaces |
|---|---|---|
area/core |
#1a5276 |
(new) — Application, State, Graph, Actions |
area/ui |
#1B2B4A |
ui |
area/storage |
#AB74C0 |
storage |
area/streaming |
#29C8CA |
parallelism |
area/hooks |
#D17E0D |
hooks |
area/tracking |
#9ECD0C |
visibility |
area/integrations |
#EA1850 |
integrations |
area/visualization |
#0052cc |
visualization |
area/website |
#6f42c1 |
(new) |
area/ci |
#bfd4f2 |
(new) — workflows, build, release scripts |
area/examples |
#EFFAAD |
examples |
area/typing |
#c5def5 |
(new) — mypy, type hints, pydantic |
priority/ — How urgent (required after triage)
| Label | Color | Criteria |
|---|---|---|
priority/critical |
#b60205 |
Blocks release or breaks core functionality |
priority/high |
#d93f0b |
Affects many users, needs action within weeks |
priority/medium |
#fbca04 |
Important but not urgent |
priority/low |
#0e8a16 |
Nice-to-have, backlog |
status/ — Where it is in the workflow
| Label | Color | Replaces |
|---|---|---|
status/needs-triage |
#BBEC04 |
triage |
status/needs-info |
#f9d0c4 |
(new) — waiting on author |
status/accepted |
#0e8a16 |
(new) — triaged, validated, ready to work on |
status/blocked |
#b60205 |
(new) — depends on another issue/PR/decision |
status/wontfix |
#ffffff |
wontfix |
pr/ — PR workflow (PRs only)
| Label | Color | When to use |
|---|---|---|
pr/do-not-merge |
#b60205 |
Blocks merge, needs more work |
pr/ready-to-merge |
#0e8a16 |
Reviewed, CI green, good to go |
pr/needs-rebase |
#fbca04 |
Conflicts with main |
pr/stale |
#e6e6e6 |
No activity for 14+ days after review |
lifecycle/ — Long-term issue management
| Label | Color | When to use |
|---|---|---|
lifecycle/stale |
#e6e6e6 |
No activity for 90 days |
lifecycle/frozen |
#d4c5f9 |
Protected from auto-close (roadmap items, umbrellas) |
Special labels (kept as-is)
| Label | Note |
|---|---|
good first issue |
GitHub recognizes natively |
help wanted |
GitHub recognizes natively |
release |
Rename from release-issues |
dependencies |
Keep, used by dependabot |
gsoc |
Rename from gsoc2026 to be timeless |
breaking-change |
New, for PRs that break compatibility |
hacktoberfest |
Annual Event - Seasoned Event |
Labels to delete
invalid, duplicate, launch, exploratory, product direction, design decision, hamilton, AWS, gsoc2026, javascript, release-issues, exceptions, triage, bug, documentation, enhancement, question, wontfix, repo hygiene, parallelism, visibility, ui, storage, integrations, visualization, hooks, examples, umbrella
(All replaced by their prefix/value equivalents above)
Triage workflow
New issue opened
→ auto-apply: status/needs-triage
→ Triager adds: kind/* + area/* + priority/*
→ Triager removes: status/needs-triage
→ Triager adds: status/accepted
New PR opened
→ Triager adds: kind/* + area/*
→ If CI fails: pr/needs-rebase or comment
→ If reviewed and ready: pr/ready-to-merge
→ If 14 days without update after review: pr/stale → convert to draft
→ If 90 days without activity: lifecycle/stale → close with comment
Stale PR policy
PRs with review comments and no response for 14 days get pr/stale and are converted to draft. PRs with no activity for 90 days are closed with a comment inviting the author to reopen when ready. This keeps the open PR list honest and actionable.
Sub-issues
- chore: create new label taxonomy and remove old labels #691 Create new labels and delete unused ones
- chore: migrate open issues to new label taxonomy #692 Migrate all open issues to new taxonomy
- chore: migrate open PRs to new label taxonomy #693 Migrate all open PRs to new taxonomy
- chore: triage and close resolved issues #694 Triage and close resolved issues with no linked PR
- chore: define stale PR policy and clean up inactive PRs #695 Define stale PR policy and clean up inactive PRs
- chore: set up auto-labeling for new issues #696 Set up GitHub Actions for auto-labeling
status/needs-triage
Metadata
Metadata
Assignees
Labels
No labels