# Working with Gitea: issues, milestones, PRs

Gitea is the **system of record** (CLAUDE.md §7). `BACKLOG.md` is a human-readable
mirror of the active milestone — when they disagree, Gitea wins.

## Issues

- Open issues from the templates in `.gitea/ISSUE_TEMPLATE/`:
  - **Slice** — a backlog user story (`S-NN · …`), encodes the Definition of Done.
  - **Bug** — a defect.
  - **ADR proposal** — a decision to record before coding (CLAUDE.md §14).
- Every issue gets `type:*` plus the relevant `area:*` label(s), and is assigned to
  its iteration **milestone** (`Iteration N — …`).
- Splitting a slice that grew too big: see CLAUDE.md §13 and the "How to split a
  slice" section of `BACKLOG.md`.

## Branches & commits

- Trunk-based: short-lived branches off `main`, squash-merged. Never push to `main`.
- Branch name: `<type>/<issue-number>-<slug>`, e.g. `feat/28-bff-health`.
- Conventional Commits, each referencing its issue: `feat(bff): … (refs #28)`.
- TDD order: the `test(...)` red commit precedes the `feat(...)` green commit.

## Pull requests

- Open with `tea pr create` (the Gitea CLI) or the web UI; the body uses
  `.gitea/PULL_REQUEST_TEMPLATE.md` and its DoD checklist.
- The merging PR closes its issue via `closes #NN` in the squash-commit body.
  Work that isn't finished (e.g. CI green pending a runner) uses `refs #NN` and the
  issue stays open.
- A PR needs a linked issue. Don't open one without it.

## CI gate

Until a self-hosted `respellion-linux` runner is registered, `make ci` is the gate
(it runs the same checks the workflow does). See [runbooks/ci.md](runbooks/ci.md).

## CLI cheatsheet (`tea`)

```bash
tea issues list --state open          # backlog
tea issue create --title "S-NN · …" --labels type:slice,area:bff --milestone "Iteration 1 — Walking Skeleton"
tea pr create --base main --head <branch> --title "…" --description "… closes #NN"
tea pr list                           # open PRs
tea pr merge <n> --style squash       # merge (after review)
```

## Changelog & releases

`CHANGELOG.md` is generated from commits by `git-cliff` (`make changelog`), refreshed
on tag. Versioning is **CalVer** `YYYY.MM.PATCH`; releases are published via Gitea
Releases.