Gitea-Tools/docs/label-taxonomy.md

Label Taxonomy

This document defines the canonical issue labels used by MCP workflows.

Every issue should carry:

• one type:* label
• one status:* label

Discussion-only issues must carry type:discussion.

Issue Type Labels

Label	Use
type:bug	Bug or defect
type:feature	Feature or enhancement
type:process	Process or policy work
type:workflow	Workflow automation or guidance
type:guardrail	Safety gate or guardrail
type:docs	Documentation work
type:test	Tests or test infrastructure
type:discussion	Discussion-only issue
type:umbrella	Umbrella or tracker issue
type:cleanup	Cleanup or hygiene work

Workflow Status Labels

Only one status:* label should be active on an issue at a time. When an issue moves forward, tooling must remove the old status:* label and apply the new one.

Label	Use
status:triage	Issue needs triage
status:ready	Issue is ready for work
status:claimed	Issue is claimed
status:in-progress	Issue is being worked on
status:blocked	Issue is blocked
status:needs-review	Issue work needs review
status:pr-open	A linked PR is open
status:approved	Linked PR is approved
status:merged	Linked PR is merged
status:reconcile	Issue needs reconciliation
status:done	Issue workflow is complete
status:duplicate	Issue is a duplicate
status:wontfix	Issue will not be fixed

Transition Rules

Suggested lifecycle:

1. New issue created: status:triage or status:ready
2. Issue selected by an author: status:claimed
3. Author starts work: status:in-progress
4. Work is blocked: status:blocked
5. PR opened: status:pr-open
6. PR approved: status:approved
7. PR merged but issue still needs closure/reconciliation: status:reconcile
8. Issue fully complete: status:done
9. Duplicate issue: status:duplicate
10. Won't-fix issue: status:wontfix

The helper module issue_workflow_labels.py is the source of truth for the canonical label specs and status transition replacement behavior.

Discussion Issues

Discussion issues must be labeled type:discussion.

A discussion issue should not be treated as implementation-ready unless it also has a clear implementation status and next action.

If a discussion produces implementation work, either:

1. convert the discussion issue into an implementation issue by changing labels and adding acceptance criteria, or
2. create child implementation issues and leave the discussion issue as type:discussion.

Tooling

• manage_labels.py --create-labels creates the canonical type:* and status:* labels.
• gitea_create_issue recommends type:* and status:* labels when missing and can apply supplied label names.
• gitea_mark_issue(..., action="start") replaces old status:* labels with status:in-progress.
• gitea_create_pr fails closed before PR creation if status:pr-open cannot be applied to the locked issue, then applies it after the PR is created.
• gitea_set_issue_labels accepts an explicit worktree_path so author sessions can satisfy the branches-only mutation guard while changing labels.

Existing Non-Workflow Labels

Existing non-workflow labels such as mcp, workflow, labels, tracker, jenkins, glitchtip, documentation, and testing remain valid topical labels. They do not replace the required type:* and status:* labels.