archvillainetteandClaude Opus 5
12b4713b95
ci / ci (pull_request) Successful in 3m36s
Corrects the bullet added in the previous commit. It read "tea api can read
but not write", which described the symptom rather than the rule.
`tea api` sends only the login's `token:` field and never signs requests with
the SSH key, so on an SSH-only login every authenticated call fails with
`{"message":"token is required"}` — writes and authenticated reads alike.
Anonymous reads against these public repos still succeed, which is why it
looked like a read/write split. Adding a token to the login makes the raw
endpoints work in both directions, confirmed by a POST to the issue labels
endpoint that applied and read back.
The `tea issues` / `tea pr` subcommands authenticate over SSH and keep working
with no token at all. That asymmetry is the confusing part, so it is now
stated outright.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
110 lines
4.9 KiB
Markdown
110 lines
4.9 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 (needs tea >= 0.15 for org labels)
|
|
tea issues edit <n> --add-labels "Kind/Bug,Priority/High"
|
|
|
|
# read the result back — exit 0 is not evidence the label applied
|
|
tea api "repos/ShadowsOverWestgate/<repo>/issues/<n>"
|
|
```
|
|
|
|
`tea api` sends only the login's `token:` and never your SSH key, so on an
|
|
SSH-only login every authenticated call fails with
|
|
`{"message":"token is required"}` while anonymous reads still work. Add a token
|
|
to `~/.config/tea/config.yml` if you want the raw endpoints. `tea issues edit`
|
|
needs no token.
|
|
|
|
## 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.
|