53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# 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.
|