register-referentie/docs/gitea-workflow.md

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.

CLI cheatsheet (tea)

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.