From 91ac3b37cf5909dfb42a476ac28ea012f3124b6f Mon Sep 17 00:00:00 2001 From: Jan Novak Date: Tue, 5 May 2026 21:52:25 +0200 Subject: [PATCH] docs: Add branch-per-feature + Gitea MR workflow to CLAUDE.md Feature work now goes on feat/ branches; Claude pushes and prints the Gitea compare URL for the user to open the MR. Exceptions documented for small fixes and typo tweaks. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 28 +++++++ ...-05-05-2144-branch-per-feature-workflow.md | 83 +++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/plans/2026-05-05-2144-branch-per-feature-workflow.md diff --git a/CLAUDE.md b/CLAUDE.md index bda0b50..870fbdb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -92,6 +92,34 @@ Tiers are set in column B of the attendance sheet: `/qr?account=…&amount=…&message=…` generates a Czech QR Platba PNG (SPD format). +## Branching & merge requests + +The remote is Gitea (`gitea.home.hrajfrisbee.cz/kacerr/fuj-management`). +For **features**, do not commit to `main` directly. Use a branch + merge +request flow: + +1. **Create a branch off `main`** before starting work: + - `feat/` for features (e.g. `feat/qr-code-overlay`) + - `fix/` for bug-fix branches the user explicitly asks for + - `` is short kebab-case +2. **Commit on the branch** following the existing commit conventions + (Co-Authored-By trailer, etc.). +3. **Push the branch** to `origin` with `-u` so it tracks. +4. **Print the Gitea compare URL** so the user can open the MR in the browser: + `https://gitea.home.hrajfrisbee.cz/kacerr/fuj-management/compare/main...` + Do **not** use `tea`, `gh`, or call the Gitea API — the user opens and + merges the MR themselves. +5. **Do not merge or delete the branch** from the CLI. The user does that + in Gitea. + +**Exceptions — when committing straight to `main` is fine:** +- Small bug fixes / hotfixes the user describes as such. +- Typo / comment / formatting tweaks. +- Edits the user explicitly says to push to `main`. + +When uncertain whether something is a feature or a small fix, ask before +committing. + ## Git Commits When making git commits, always append yourself as co-author trailer to the end of the commit message to indicate AI assistance diff --git a/docs/plans/2026-05-05-2144-branch-per-feature-workflow.md b/docs/plans/2026-05-05-2144-branch-per-feature-workflow.md new file mode 100644 index 0000000..55fefb2 --- /dev/null +++ b/docs/plans/2026-05-05-2144-branch-per-feature-workflow.md @@ -0,0 +1,83 @@ +# Branch-per-feature + Gitea MR workflow + +## Context + +Until now, Claude has been committing feature work directly to `main` +(see recent history: `feat: Lower adult monthly fee…`, `feat: Go rewrite M1…`, +all on `main`). The user wants to switch to a branch-per-feature flow with +review via a Gitea merge request, so that: + +- Feature work is reviewable as a self-contained diff before it lands. +- `main` stays releasable. +- The change history shows reviewed merges, not unsupervised pushes. + +The remote is Gitea (`https://gitea.home.hrajfrisbee.cz/kacerr/fuj-management.git`), +which supports the standard pull/merge-request flow. + +This plan only modifies `CLAUDE.md`. No code changes. + +## Scope clarification (from user) + +- **MR creation method:** Claude pushes the branch and prints the Gitea + "compare" URL. The user opens / merges the MR in the browser. No `tea` CLI, + no API calls. +- **When the flow applies:** Features only. Small bug fixes and hotfixes can + still be committed straight to `main`. Claude decides feature-vs-fix based + on scope; when uncertain, ask. +- **Branch naming:** `feat/` for features, `fix/` for the + occasional bug-fix branch the user explicitly requests. `` is + kebab-case, short, descriptive. + +## Change + +Add a new top-level section to `CLAUDE.md` titled **"Branching & merge requests"**, +placed immediately before the existing `## Git Commits` section so the workflow +context appears before the commit-message convention. + +### Proposed section content + +```markdown +## Branching & merge requests + +The remote is Gitea (`gitea.home.hrajfrisbee.cz/kacerr/fuj-management`). +For **features**, do not commit to `main` directly. Use a branch + merge +request flow: + +1. **Create a branch off `main`** before starting work: + - `feat/` for features (e.g. `feat/qr-code-overlay`) + - `fix/` for bug-fix branches the user explicitly asks for + - `` is short kebab-case +2. **Commit on the branch** following the existing commit conventions + (Co-Authored-By trailer, etc.). +3. **Push the branch** to `origin` with `-u` so it tracks. +4. **Print the Gitea compare URL** so the user can open the MR in the + browser: + `https://gitea.home.hrajfrisbee.cz/kacerr/fuj-management/compare/main...` + Do **not** use `tea`, `gh`, or call the Gitea API — the user opens and + merges the MR themselves. +5. **Do not merge or delete the branch** from the CLI. The user does that + in Gitea. + +**Exceptions — when committing straight to `main` is fine:** +- Small bug fixes / hotfixes the user describes as such. +- Typo / comment / formatting tweaks. +- Edits the user explicitly says to push to `main`. + +When uncertain whether something is "feature" or "small fix", ask before +committing. +``` + +## Files to modify + +- [CLAUDE.md](CLAUDE.md) — insert the new `## Branching & merge requests` + section just above the existing `## Git Commits` section (around line 95). + +## Verification + +- Re-read `CLAUDE.md` and confirm the new section is well-placed and the + existing structure (`## Git Commits`, `## Changelog`, `## Plans`) is intact. +- `git diff CLAUDE.md` should show only an additive change. +- No code, tests, or runtime behavior changes — nothing else to test. +- Behavior verification happens on the **next** feature request: Claude + should create a `feat/` branch, commit there, push, and print the + compare URL instead of committing on `main`.