Repo governance: label taxonomy, triage workflow, and PR lifecycle

[andreahlert]

Context

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.

Since 0.41.0-incubating already passed IPMC vote, and the project has grown significantly, it was time to professionalize issue/PR management.

Current state

• All open issues and PRs use the new prefix/value taxonomy (kind/*, area/*, priority/*)
• 40 new labels created, 27 legacy labels deleted
• gsoc2026 renamed to gsoc, release-issues renamed to release
• Full triage completed: 21 stale/resolved issues closed

Label Taxonomy

Convention: prefix/value (scannable, filterable, consistent)

kind/ — What it is (required on every issue and PR)

Label	Color	When to use
kind/bug	#d73a4a	Something is broken
kind/feature	#a2eeef	Net-new functionality
kind/improvement	#7fd4f2	Improving something that already exists
kind/documentation	#0075ca	Docs, examples, notebooks
kind/cleanup	#e6e6e6	Refactor, typos, tech debt
kind/question	#d876e3	Usage questions
kind/umbrella	#50645A	Tracking issue grouping sub-issues

area/ — Where in the codebase (at least 1 per issue/PR)

Label	Color	Description
area/core	#1a5276	Application, State, Graph, Actions
area/ui	#1B2B4A	Burr UI (telemetry frontend)
area/storage	#AB74C0	Persisters, state storage
area/streaming	#29C8CA	Streaming actions, parallel streams
area/hooks	#D17E0D	Lifecycle hooks, interceptors
area/tracking	#9ECD0C	Telemetry, tracing, OpenTelemetry
area/integrations	#EA1850	External integrations (LLMs, frameworks)
area/visualization	#0052cc	Graph visualization, diagrams
area/website	#6f42c1	burr.apache.org website
area/ci	#bfd4f2	Workflows, build, release scripts
area/examples	#EFFAAD	Relates to /examples
area/typing	#c5def5	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	When to use
status/needs-triage	#BBEC04	New issue, needs triage
status/needs-info	#f9d0c4	Waiting on author response
status/accepted	#0e8a16	Triaged, validated, ready to work on
status/blocked	#b60205	Depends on another issue/PR/decision
status/wontfix	#ffffff	Decided not to fix

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	Release-related issues
dependencies	Used by dependabot
gsoc	Google Summer of Code
breaking-change	PRs that break backward compatibility
hacktoberfest	Annual event

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
• 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 and PRs #696 Set up GitHub Actions for auto-labeling status/needs-triage
• chore: define issue assignment policy #709 Define issue assignment policy

[andreahlert]

@skrawcz @elijahbenizzy - I would love your opinions about this, before starting.

[skrawcz]

CC @jernejfrank @rgareev for thoughts

[skrawcz]

@andreahlert looks good. I would add hacktoberfest label since that comes around every year.

[andreahlert]

@andreahlert looks good. I would add hacktoberfest label since that comes around every year.

Kept as a Special label

[elijahbenizzy]

Thie seems reasonable, thanks for digging in!

[andreahlert]

Labels migrated to new taxonomy (#692).