99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# 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.
|