Madhura68
7d5fb35964
Werker-flow docs aangepast naar het hybride model: `origin` is Forgejo, de worker maakt geen GitHub-PR meer; die ontstaat via een handmatig getriggerde promote-Action in Forgejo. - docs/runbooks/forgejo-hybrid-flow.md: nieuw canoniek runbook met het flow-diagram, de promote-stap en main-sync. - CLAUDE.md: stap 1 + stap 8 + Hardstop "Push" verwijzen naar het nieuwe runbook. - AGENTS.md: tabel-rij "Queue leeg" + PBI-86-toelichting. - docs/runbooks/branch-and-commit.md: intro herschreven (Vercel-cost verschuift naar promote-trigger), agent-batch-flow tabel + E2E- verificatie + rebase-noot bijgewerkt. - docs/runbooks/auto-pr-flow.md: DEPRECATED-banner; document blijft als historische referentie. - docs/manual/03-git-workflow.md: rule 3 (push), rule 5 (auto-PR → promote) en de merge-conflicts tabel. - docs/manual/04-mcp-integration.md: mermaid-stap aangepast. - docs/manual/05-docker.md: GITHUB_TOKEN-beschrijving verduidelijkt (optioneel; niet meer nodig voor de worker zelf). - docs/INDEX.md: regen via npm run docs (113 docs). npm run verify groen: 924 tests, typecheck clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
161 lines
7.1 KiB
Markdown
161 lines
7.1 KiB
Markdown
---
|
|
title: "Branch, PR & Commit Strategy"
|
|
status: active
|
|
audience: [ai-agent, contributor]
|
|
language: nl
|
|
last_updated: 2026-05-03
|
|
when_to_read: "Before creating a branch, commit, or PR. Also before any agent-batch run."
|
|
---
|
|
|
|
# Branch, PR & Commit Strategy
|
|
|
|
## Branch & PR Strategy (STRICT — kostenbeheersing)
|
|
|
|
> **Core rule: één branch per milestone, PR alleen na gebruikerstest**
|
|
|
|
Sinds **PBI-86** is `origin` voor de Scrum4Me-repos de zelf-gehoste Forgejo
|
|
(zie [forgejo-hybrid-flow.md](./forgejo-hybrid-flow.md)). De worker pusht
|
|
daar naartoe — die push triggert géén Vercel-deploy. Vercel-previews
|
|
ontstaan pas wanneer je de **promote-Action** in Forgejo handmatig triggert,
|
|
die op zijn beurt een branch + PR op GitHub aanmaakt. Op het huidige
|
|
Hobby-account zijn previews schaars en kosten geld; we minimaliseren ze tot
|
|
er werkelijk iets te reviewen valt.
|
|
|
|
### Wel doen
|
|
|
|
- Eén branch voor de hele milestone — `feat/M{N}-{slug}` (bv. `feat/M10-qr-login`); voor losse stories zonder milestone blijft `feat/ST-XXX-{slug}` geldig
|
|
- Commits accumuleren lokaal volgens de Commit Strategy hieronder — één commit per stap, ST-code in de titel
|
|
- Pushen + PR openen **pas nadat de gebruiker de milestone handmatig heeft getest en goedgekeurd** — vraag expliciet om bevestiging vóór `git push`
|
|
- Tussentijdse "klaar voor jouw test"-momenten markeren met een lokale tag of een berichtje in chat, niet met een push
|
|
|
|
### Niet doen
|
|
|
|
- Pushen na elke story of commit
|
|
- Een PR per story openen tijdens de implementatie
|
|
- "Just-in-case" pushen om backup te hebben — gebruik `git stash`, een lokale tag, of meerdere lokale branches
|
|
- `--force-push` om eerdere preview-builds "weg te toveren" (kost dezelfde build opnieuw bij hercreatie)
|
|
- **Direct pushen naar `main`** — die branch heeft protection rules; gebruik altijd een PR
|
|
|
|
### Wanneer wel commit-zonder-vragen, wanneer niet
|
|
|
|
- **Tijdens een directed sprint-flow** (Track A: `mcp__scrum4me__implement_next_story` of een expliciete *"implementeer M{N}"*-opdracht): commit-per-laag conform de Commit Strategy hieronder is impliciet geautoriseerd — niet per commit vragen
|
|
- **Bij ad-hoc / out-of-band werk** (bug-fix tussendoor, refactor, kleine wijziging op verzoek): toon de diff + voorgestelde commit-message en wacht op `"commit it"` voordat je `git commit` draait
|
|
- **`git push` is altijd expliciet** — de scope van de policy gaat over preview-builds, dus push gebeurt alleen na gebruiker-test, ongeacht commit-context
|
|
|
|
### Uitzonderingen op de push-regel
|
|
|
|
- Een **planning-PR** zonder code-wijzigingen (alleen docs in `docs/plans/` of `docs/`) mag direct gepusht worden — die triggert geen functional regressie en is goedkoop te bouwen
|
|
- Een **bugfix-hotfix** op `main` met aantoonbare productie-impact mag direct gepusht worden (via een PR — zie boven)
|
|
|
|
### Wanneer aanpassen
|
|
|
|
Zodra het Vercel-account naar Pro (of andere omgeving zonder per-build-kosten) gaat: vervang deze regel door "branch + PR per story" zoals oorspronkelijk in dit document stond. Werk deze sectie bij én documenteer de wijziging in `docs/decisions/agent-instructions-history.md`.
|
|
|
|
### Agent-batch flow (verplicht voor worker-runs)
|
|
|
|
Wanneer de NAS-agent (`/opt/agent/`) een batch jobs uitvoert:
|
|
|
|
| Moment | Actie | Verbod |
|
|
|---|---|---|
|
|
| Start run | `git checkout -b feat/<batch-slug>` lokaal | `gh pr create` |
|
|
| Na elke taak | `git add -A && git commit -m "<type>(ST-XXX): <title>"` | `git push` |
|
|
| Queue leeg | `git push -u origin <branch>` (Forgejo) | `gh pr create` — GitHub-PR via de promote-Action |
|
|
|
|
- Alle commits accumuleren op dezelfde branch — lopende state blijft op disk tot de run klaar is.
|
|
- Één PR per batch → één Vercel preview-deployment.
|
|
- Single-task batch (1 job in queue): dezelfde flow — 1 commit → push + PR.
|
|
|
|
#### End-to-end verificatie
|
|
|
|
Gebruik deze checklist om te verifiëren dat de batch-flow correct werkt na
|
|
een agent-run:
|
|
|
|
**Voorbereiding**
|
|
1. Seed ≥ 2 taken onder één story (bv. README-edits).
|
|
2. Trigger de batch via **"Voer alle uit"** op het Solo Board.
|
|
3. Wacht tot de agent alle jobs als `done` markeert.
|
|
|
|
**Forgejo-checks** (worker-output)
|
|
- [ ] Er is precies **één branch** op Forgejo voor de batch (`feat/<batch-slug>`).
|
|
- [ ] De branch bevat **één commit per taak** (geen squash, geen force-push).
|
|
- [ ] Er is **geen** GitHub-PR vanuit de worker aangemaakt.
|
|
|
|
**Pas na promote** (handmatig via Forgejo Action — zie [forgejo-hybrid-flow.md](./forgejo-hybrid-flow.md))
|
|
- [ ] Eén GitHub-PR voor de gepromote branch.
|
|
- [ ] Vercel-dashboard → Deployments: **exact één preview-deployment** voor die PR.
|
|
|
|
**Race-condition scenario**: als een nieuwe taak in de queue terechtkomt
|
|
terwijl de agent de queue-check uitvoert, kan er een tweede push (naar
|
|
Forgejo) volgen. Acceptabel — de extra commits komen vanzelf mee bij de
|
|
volgende promote.
|
|
|
|
### Merge conflicten — wanneer wel/niet?
|
|
|
|
Een veelgestelde vraag: "als meerdere stories dezelfde bestanden raken, krijgen we dan geen merge conflicten?"
|
|
|
|
**Binnen dezelfde batch (zelfde branch):** nee. Story B commit bovenop Story A op dezelfde branch — lineair, geen conflict. Dit is precies waarom de workflow één branch per batch voorschrijft in plaats van één per story.
|
|
|
|
**Tussen parallelle batches (verschillende branches richting `main`):** ja, mogelijk. Als batch X en batch Y allebei dezelfde file aanpassen en allebei willen mergen, krijgt de tweede een rebase-conflict.
|
|
|
|
Mitigaties:
|
|
1. **Seriële PRs** — start een nieuwe batch pas als de vorige PR gemerged is. De MCP `get_claude_context`-flow stuurt hier al op (één story tegelijk per agent).
|
|
2. **Slim batchen** — stories die hetzelfde domein raken (bv. alles rond Sprint Board) horen in dezelfde batch, niet verspreid over batches.
|
|
3. **Rebase vóór push** — `git fetch origin main && git rebase origin/main` vóór de push (en vóór een promote) lost kleine drift op zonder conflict.
|
|
|
|
---
|
|
|
|
## Plan Mode
|
|
|
|
- Voor simpele, goed-afgebakende file-edits: **niet** in plan mode gaan — gewoon de wijziging maken
|
|
- Reserveer plan mode voor multi-step refactors, ambigue verzoeken, of milestone-planning waarbij design-keuzes vooraf bevestigd moeten worden
|
|
- Plannen die uit plan mode komen: opslaan als `docs/plans/M{N}-{slug}.md` (zie memory `feedback_plan_location`), niet als ephemeral systeem-bestand
|
|
|
|
---
|
|
|
|
## Commit Strategy (STRICT)
|
|
|
|
> **Core rule: één commit = één verantwoordelijkheid**
|
|
|
|
### Nooit doen
|
|
|
|
- Database + API + UI in één commit mengen
|
|
- Feature + documentatie combineren
|
|
- Grote "alles gewijzigd" commits
|
|
- Vage berichten zoals "update stuff"
|
|
|
|
### Verplichte structuur
|
|
|
|
Splits werk op in logische lagen:
|
|
|
|
1. Database / Prisma
|
|
2. API / server actions
|
|
3. UI / components
|
|
4. Config / infra
|
|
5. Documentatie
|
|
|
|
### Commit-formaat
|
|
|
|
```
|
|
feat(ST-XXX): korte beschrijving
|
|
fix(ST-XXX): korte beschrijving
|
|
chore(ST-XXX): korte beschrijving
|
|
docs(ST-XXX): korte beschrijving
|
|
```
|
|
|
|
### Voorbeeld (verplicht patroon)
|
|
|
|
In plaats van:
|
|
|
|
```bash
|
|
feat: add profile system
|
|
```
|
|
|
|
Splits altijd op in:
|
|
|
|
```bash
|
|
feat(ST-XXX): add user profile fields to Prisma schema
|
|
feat(ST-XXX): add avatar upload endpoint
|
|
feat(ST-XXX): add profile editor component
|
|
chore(ST-XXX): configure sharp for avatar processing
|
|
docs(ST-XXX): document profile feature
|
|
```
|