From 0b8419dffba2be77f44631f3a1f2c1edf7b58106 Mon Sep 17 00:00:00 2001 From: Thom Lamb Date: Thu, 20 Aug 2026 11:02:29 -0500 Subject: [PATCH] docs: require an issue behind every branch and PR (#77) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documented convention allowed dropping the issue number when no issue existed. The clause looks harmless — it was meant for trivial work — but in practice it turns "there is no issue yet" into "there is no issue ever", and two branches went that way this week: the app icon, merged as #70, and the header mark, which had to be filed retroactively as #76. Both were legitimate work that the tracker never heard about, and the convention is what permitted it. The cost is not bookkeeping. The issue is where the reasoning, the rejected alternatives, and the verification end up — the record that outlives the conversation that produced it. A branch with nothing behind it leaves that nowhere but a commit message. Everything else about the convention is unchanged: the type prefixes, the (#N) subject, the Closes #N body line, and the point that Gitea builds the link from the commit rather than the branch name. Closes #77 --- .claude/project-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/project-context.md b/.claude/project-context.md index 0039d0a..0859bd3 100644 --- a/.claude/project-context.md +++ b/.claude/project-context.md @@ -214,7 +214,7 @@ sudo docker exec -it redefined-designs-db-syn psql -U redefined -d redefined -c ## Conventions - **Never commit directly to `main`.** Always branch, open a PR, merge; the branch auto-deletes (repo setting is on). -- **Branches follow [Conventional Branch](https://conventional-branch.github.io/), with the issue number carried for Gitea:** `/-`, e.g. `feature/48-my-account-modal`, `bugfix/57-cart-total-wrong`. Types are `feature`, `bugfix`, `hotfix`, `release`, `chore` — the same `feature/` prefix this repo has always used, so nothing in the existing history is wrong. Drop the number when there is no issue behind the work (`chore/tidy-dead-routes`). The type should agree with the Conventional Commit type of the work it carries. +- **Branches follow [Conventional Branch](https://conventional-branch.github.io/), with the issue number carried for Gitea:** `/-`, e.g. `feature/48-my-account-modal`, `bugfix/57-cart-total-wrong`. Types are `feature`, `bugfix`, `hotfix`, `release`, `chore` — the same `feature/` prefix this repo has always used, so nothing in the existing history is wrong. **Every branch and every PR has an issue behind it — no exceptions.** When work arrives through conversation rather than the tracker, file the issue first and branch from it; do not start a branch meaning to retrofit an issue later. The escape hatch that used to sit here turned "no issue yet" into "no issue ever", and two branches went that way before it was removed (#70 and #76). The type should agree with the Conventional Commit type of the work it carries. - **Commits follow [Conventional Commits](https://www.conventionalcommits.org/)** — `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `ci:`, `refactor:` — with the issue number appended to the subject: `feat(account): open My Account as a modal (#48)`. - **Put `Closes #48` in the commit body**, on its own line, for the commit that completes the issue (`Refs #48` when it only contributes). This is what actually closes the issue on merge, independently of whether the PR description repeats it. - **Be clear about which part does the linking.** Gitea creates the reference from a `#48` appearing in a *commit message or PR* — never from the branch name. The branch name is for humans reading `git branch`; the reference is what ties the work to the issue. Both are wanted, but only one of them links.