107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# Issue tracker: Gitea
|
|
|
|
Issues and specs for this repo live as Gitea issues. Use the
|
|
[`tea`](https://gitea.com/gitea/tea) CLI for all operations.
|
|
|
|
## Repository context
|
|
|
|
Run commands inside the clone so `tea` can infer the repository and login from
|
|
its Git remote. If the clone has multiple Gitea remotes or logins, pass
|
|
`--remote <name>` or `--login <name>`. Use `--repo <owner>/<repo>` only outside
|
|
the clone.
|
|
|
|
Before the first operation, verify the instance with
|
|
`tea logins list --output json`. If it is missing, ask the user to run
|
|
`tea login add`; never ask for or handle their access token.
|
|
|
|
## Conventions
|
|
|
|
- **Create an issue**: `tea issues create --title "..." --description "..."`.
|
|
For a multi-line body, use shell command substitution around a quoted heredoc:
|
|
|
|
```bash
|
|
tea issues create --title "..." --description "$(cat <<'EOF'
|
|
Multi-line issue body.
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
- **Read an issue with comments**:
|
|
`tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
|
|
- **List issues**:
|
|
`tea issues list --state open --fields index,state,author,url,title,body,assignees,labels,comments --output json`,
|
|
adding `--labels "label-one,label-two"`, `--assignee <user>`, or another
|
|
supported filter as needed. Paginate with `--page` and `--limit`; do not
|
|
assume the default first 30 results are complete.
|
|
- **Comment on an issue**: `tea comments add <number> --description "..."`.
|
|
- **Apply or remove labels**: `tea issues edit <number> --add-labels "..."` or
|
|
`--remove-labels "..."`. Separate multiple labels with commas.
|
|
- **Assign or unassign**: `tea issues edit <number> --add-assignees "..."` or
|
|
`--remove-assignees "..."`.
|
|
- **Close**: post the closing explanation with
|
|
`tea comments add <number> --description "..."`, then run
|
|
`tea issues close <number>`.
|
|
- **Reopen**: `tea issues reopen <number>`.
|
|
- **Raw API fallback**: use `tea api '<endpoint>'` only for a Gitea feature
|
|
without a first-class `tea` command. Prefer `{owner}` and `{repo}`
|
|
placeholders so repository context remains explicit.
|
|
|
|
Use `--output json` for machine-readable reads. Do not scrape table output.
|
|
|
|
## Pull requests as a triage surface
|
|
|
|
**PRs as a request surface: no.** _(Set this to `yes` if this repo treats
|
|
external pull requests as feature requests; `/triage` reads this flag.)_
|
|
|
|
When set to `yes`, PRs use the same labels and states as issues:
|
|
|
|
- **Read a PR with comments and diff**:
|
|
`tea pulls <number> --comments --fields index,state,author,url,title,body,diff,assignees,labels,comments --output json`.
|
|
- **List open PRs**:
|
|
`tea pulls list --state open --fields index,state,author,author-id,url,title,body,assignees,labels,comments --output json`.
|
|
Determine whether an author is external from the repository's Gitea membership
|
|
data; the PR listing does not classify author membership.
|
|
- **Comment**: `tea comments add <number> --description "..."`.
|
|
- **Apply or remove labels**: `tea pulls edit <number> --add-labels "..."` or
|
|
`--remove-labels "..."`.
|
|
- **Close**: `tea pulls close <number>`.
|
|
|
|
Gitea pull requests use the repository's issue index space, so `#42` may refer
|
|
to either surface. If the context is unclear, inspect it with
|
|
`tea pulls 42 --output json`; if that command reports no PR, read it with
|
|
`tea issues 42 --output json`.
|
|
|
|
## When a skill says "publish to the issue tracker"
|
|
|
|
Create a Gitea issue with `tea issues create`.
|
|
|
|
## When a skill says "fetch the relevant ticket"
|
|
|
|
Run
|
|
`tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
|
|
|
|
## Wayfinding operations
|
|
|
|
`/wayfinder` uses one **map** issue with linked **child** issues. These
|
|
conventions store relationships in issue bodies, so they work across Gitea
|
|
versions.
|
|
|
|
- **Map**: create one issue labelled `wayfinder:map` containing the Notes,
|
|
Decisions-so-far, and Fog sections. Use
|
|
`tea issues create --labels "wayfinder:map"` with its title and description.
|
|
- **Child ticket**: start the body with `Part of #<map>` and apply a
|
|
`wayfinder:<type>` label: `research`, `prototype`, `grilling`, or `task`. Add
|
|
each child as a task-list item in the map body to preserve frontier order.
|
|
- **Blocking**: put `Blocked by: #<n>, #<n>` near the top of the child body. A
|
|
ticket becomes unblocked after every referenced blocker closes.
|
|
- **Frontier query**: list all open children, order them by the map's task list,
|
|
and discard tickets with an open blocker or an assignee. Select the first
|
|
remaining ticket. Fetch each referenced blocker; do not infer its state from
|
|
map text.
|
|
- **Claim**: resolve the active username with `tea whoami`, then run
|
|
`tea issues edit <n> --add-assignees "<username>"` as the session's first
|
|
write. Do not assume `@me` works.
|
|
- **Resolve**: run `tea comments add <n> --description "<answer>"`, close the
|
|
child with `tea issues close <n>`, then append a context pointer and link to
|
|
the map's Decisions-so-far section.
|