archvillainette
f395d86db5
`docs/agents/triage-labels.md` named five labels that do not exist in the tracker (`needs-triage`, `needs-info`, `ready-for-human`, `wontfix`). Meanwhile the org has an 18-label taxonomy at https://git.westgate.pw/org/ShadowsOverWestgate/settings/labels that agents never touched, because no doc pointed at it — `Kind/Bug` had been used twice across every repo. This replaces the doc with the real taxonomy and makes one `Kind/*` label required on every issue and PR at creation time. `AGENTS.md` gets the short version. Enforcement lands separately in `sow-platform` (`ops/policy/labels.yml` + a nightly `ops/checks/check-labels.sh` drift check). Identical doc change in every `sow-*` repo.Reviewed-on: #97 Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
102 lines
4.5 KiB
Markdown
102 lines
4.5 KiB
Markdown
# Issue and PR labels
|
|
|
|
Labels are **org-wide**. They are defined once, for the whole
|
|
`ShadowsOverWestgate` org, at
|
|
<https://git.westgate.pw/org/ShadowsOverWestgate/settings/labels>, and every
|
|
repo in the org can use them. Never create a per-repo copy of a label that
|
|
already exists at org level.
|
|
|
|
## The rule
|
|
|
|
**Every issue and every pull request gets exactly one `Kind/*` label, at the
|
|
moment it is created.** Not later, not "when someone triages it". If you open
|
|
it, you label it.
|
|
|
|
An issue with no `Kind/*` label is untriaged. That is the only meaning of
|
|
"untriaged" here — there is no `needs-triage` label.
|
|
|
|
The other groups are optional, and each one is *exclusive*: an issue can carry
|
|
at most one `Priority/*`, one `Status/*`, and one `Reviewed/*`. Gitea enforces
|
|
this.
|
|
|
|
```sh
|
|
# always from inside the owning repo's clone
|
|
tea issues create --title "..." --description "..." --labels "Kind/Bug" </dev/null
|
|
tea pr create --title "..." --description "..." --labels "Kind/Feature" </dev/null
|
|
|
|
# add a label to something that already exists
|
|
tea api --method POST "repos/ShadowsOverWestgate/<repo>/issues/<n>/labels" \
|
|
--data '{"labels":["Kind/Bug","Priority/High"]}'
|
|
```
|
|
|
|
## Kind — what this is (pick exactly one)
|
|
|
|
| Label | Use it when |
|
|
| -------------------- | --------------------------------------------------------------- |
|
|
| `Kind/Bug` | Something that used to work, or is documented to work, does not |
|
|
| `Kind/Feature` | New functionality that does not exist yet |
|
|
| `Kind/Enhancement` | Existing functionality gets better, faster, or nicer |
|
|
| `Kind/Documentation` | Docs, ADRs, runbooks, agent guides |
|
|
| `Kind/Testing` | Tests, CI checks, contract scripts |
|
|
| `Kind/Security` | Secrets, auth, permissions, hardening, a vulnerability |
|
|
|
|
Bug vs Enhancement, when it is unclear: if the current behaviour is wrong, it
|
|
is a bug. If the current behaviour is right but weak, it is an enhancement.
|
|
|
|
## Priority — how urgent (optional, at most one)
|
|
|
|
`Priority/Critical`, `Priority/High`, `Priority/Medium`, `Priority/Low`.
|
|
|
|
Leave it off if you do not know. A wrong priority is worse than none.
|
|
|
|
## Status — why it is not moving (optional, at most one)
|
|
|
|
| Label | Meaning |
|
|
| ----------------------- | -------------------------------------------- |
|
|
| `Status/Blocked` | Waiting on another issue, PR, or decision |
|
|
| `Status/Need More Info` | Waiting on the reporter or on a human answer |
|
|
| `Status/Abandoned` | Work started and stopped; nobody is on it |
|
|
|
|
## Reviewed — the verdict (optional, at most one)
|
|
|
|
`Reviewed/Confirmed`, `Reviewed/Duplicate`, `Reviewed/Invalid`,
|
|
`Reviewed/Won't Fix`. Apply one of these when closing without a fix, so the
|
|
reason survives.
|
|
|
|
## Compat
|
|
|
|
`Compat/Breaking` — add it on top of the `Kind/*` label when the change breaks
|
|
something that already works for a player, an operator, or another repo.
|
|
|
|
## Workflow labels (repo-level, not org-level)
|
|
|
|
These live in the repo, not the org, and are orthogonal to the groups above:
|
|
|
|
- `ready-for-agent` — the spec is complete; an AFK agent may pick this up.
|
|
No label means it needs a human.
|
|
- `wayfinder:map`, `wayfinder:task`, `wayfinder:research`,
|
|
`wayfinder:prototype`, `wayfinder:grilling` — set by `/wayfinder`. Leave
|
|
them alone unless you are running a wayfinder operation.
|
|
- `sow-nodebb` also has `package/*` labels naming the plugin or theme a ticket
|
|
touches.
|
|
|
|
## When a skill names a label we do not have
|
|
|
|
Skills written elsewhere (mattpocock/skills and friends) use a different
|
|
vocabulary. Translate it:
|
|
|
|
| Skill says | Do this here |
|
|
| ----------------- | ------------------------------------------------- |
|
|
| `needs-triage` | Nothing — no `Kind/*` label already means this |
|
|
| `needs-info` | `Status/Need More Info` |
|
|
| `ready-for-agent` | `ready-for-agent` |
|
|
| `ready-for-human` | Nothing — absence of `ready-for-agent` means this |
|
|
| `wontfix` | `Reviewed/Won't Fix` |
|
|
|
|
## Drift check
|
|
|
|
`ops/checks/check-labels.sh` in `sow-platform` runs nightly. It compares the
|
|
live org labels to `ops/policy/labels.yml` and lists every open issue and PR in
|
|
the org that does not have exactly one `Kind/*` label. That check is the
|
|
enforcement; this file is the rule.
|