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>
100 lines
6 KiB
Markdown
100 lines
6 KiB
Markdown
---
|
|
title: "Git Workflow"
|
|
status: active
|
|
audience: [contributor]
|
|
language: en
|
|
last_updated: 2026-05-07
|
|
when_to_read: "Before creating a branch, before committing, and especially before pushing or opening a PR."
|
|
---
|
|
|
|
# 03 — Git Workflow
|
|
|
|
The Scrum4Me git workflow is shaped by two pressures that don't usually appear together:
|
|
|
|
1. An **AI agent** that can produce many commits per hour without human review,
|
|
2. A **Vercel Hobby plan** that meters preview deployments and bills for them.
|
|
|
|
These two together drive a workflow that looks unusual compared to "feature-branch + PR-per-story". This chapter explains the *why*; the authoritative *how* lives in the runbooks linked at the bottom.
|
|
|
|
## The five guiding rules
|
|
|
|
### 1. One branch per milestone, not per story
|
|
|
|
A milestone (e.g. `M10-qr-login`) groups multiple stories that ship together. The agent runs through them on a single branch named `feat/M{N}-{slug}` (or `feat/ST-XXX-{slug}` for one-off stories without a milestone). All commits accumulate on that branch.
|
|
|
|
> **Why?** Every push to a feature branch triggers a Vercel preview build. Pushing per story would multiply the build cost without producing more reviewable units of work — the user reviews the milestone, not the story.
|
|
|
|
See [`docs/adr/0003-one-branch-per-milestone.md`](../adr/0003-one-branch-per-milestone.md) for the full rationale.
|
|
|
|
### 2. Commit per layer, not per task
|
|
|
|
A single task can touch the database, the API, and the UI. Each of those layers gets its own commit. The pattern:
|
|
|
|
```
|
|
feat(ST-XXX): add field X to Prisma schema # DB
|
|
feat(ST-XXX): add Y endpoint accepting X # API
|
|
feat(ST-XXX): wire X into the editor component # UI
|
|
chore(ST-XXX): configure sharp for X processing # config
|
|
docs(ST-XXX): document the X feature # docs
|
|
```
|
|
|
|
> **Why?** Reviewers and `git bisect` both benefit when one commit can be reverted without touching unrelated layers. A `feat: add profile system` mega-commit is an antipattern.
|
|
|
|
### 3. Push only after the user has tested
|
|
|
|
Commits accumulate **locally** until the milestone is functionally complete and the user has confirmed it works. Then — and only then — `git push` (to Forgejo, the worker's `origin` since PBI-86). The GitHub-PR comes later via the manual promote-Action — see [`forgejo-hybrid-flow.md`](../runbooks/forgejo-hybrid-flow.md).
|
|
|
|
> **Why?** Same cost reason as rule 1. Mid-milestone "save points" should be local tags or `git stash`, not pushes. Some exceptions exist (planning-only PRs, emergency hotfixes); they're enumerated in [`branch-and-commit.md`](../runbooks/branch-and-commit.md#uitzonderingen-op-de-push-regel).
|
|
|
|
### 4. One PR per batch → one preview build
|
|
|
|
When the worker runs through a queue of jobs, the entire run produces **one** PR with one commit per task. No interim pushes, no force-pushes to clean up history, no PR-per-story splits.
|
|
|
|
The end-to-end verification — that one batch produces exactly one Vercel deployment — is in [`branch-and-commit.md`](../runbooks/branch-and-commit.md) (see the *End-to-end verificatie* section).
|
|
|
|
### 5. Promote to GitHub at the end (PBI-86 hybrid model)
|
|
|
|
Once a story reaches `DONE` and the branch is pushed to Forgejo, a human operator triggers the promote-Action in Forgejo to land the branch on GitHub and open the PR. Path-filter / label rules then decide whether a Vercel deploy runs.
|
|
|
|
- **Hybrid model + promote flow**: [`docs/runbooks/forgejo-hybrid-flow.md`](../runbooks/forgejo-hybrid-flow.md)
|
|
- **Selective deploy controls** (`skip-deploy` label, path-filter for `app/`/`components/`/`lib/`): [`docs/runbooks/deploy-control.md`](../runbooks/deploy-control.md)
|
|
- **Historical auto-PR flow** (removed in T-1005…T-1007): [`docs/runbooks/auto-pr-flow.md`](../runbooks/auto-pr-flow.md)
|
|
|
|
## Commit message format
|
|
|
|
```
|
|
<type>(ST-XXX): short description
|
|
```
|
|
|
|
Where `<type>` is one of `feat`, `fix`, `chore`, `docs`. The story code in parentheses links the commit back to the Scrum4Me MCP entity.
|
|
|
|
For PBI-level work (no single story), use the PBI code: `docs(PBI-58): scaffold developer manual`.
|
|
|
|
## Merge conflicts
|
|
|
|
| Scenario | Conflict? | Mitigation |
|
|
|---|---|---|
|
|
| Multiple tasks on the same batch branch | No — they stack linearly on one branch | None needed |
|
|
| Two parallel batches touching the same files | Yes, possible | Serialise batches via the MCP `get_claude_context` flow (one story at a time per agent), or rebase before push |
|
|
| Long-lived branch drifting from `main` | Yes, possible | `git fetch origin main && git rebase origin/main` before push (and before promote to GitHub) |
|
|
|
|
`git push --force` to "wipe" earlier preview builds is forbidden — it costs the same build again on recreation, defeating the purpose of the cost-control rules.
|
|
|
|
## When **not** to follow the strict rules
|
|
|
|
When the Vercel account moves to Pro (or another billing tier without per-build cost), this workflow can revert to the more conventional "branch + PR per story". When that happens, update the rule in [`branch-and-commit.md`](../runbooks/branch-and-commit.md) and log the change in [`docs/decisions/agent-instructions-history.md`](../decisions/agent-instructions-history.md).
|
|
|
|
## Deep links
|
|
|
|
| Topic | Authoritative source |
|
|
|---|---|
|
|
| Branch & commit rules (full normative spec) | [`docs/runbooks/branch-and-commit.md`](../runbooks/branch-and-commit.md) |
|
|
| Auto-PR flow (story-DONE → merged-PR pipeline) | [`docs/runbooks/auto-pr-flow.md`](../runbooks/auto-pr-flow.md) |
|
|
| Deploy controls (labels, path-filter) | [`docs/runbooks/deploy-control.md`](../runbooks/deploy-control.md) |
|
|
| Vercel deployment specifics | [`docs/runbooks/deploy-vercel.md`](../runbooks/deploy-vercel.md) |
|
|
| Decision rationale (one-branch-per-milestone) | [`docs/adr/0003-one-branch-per-milestone.md`](../adr/0003-one-branch-per-milestone.md) |
|
|
| Worker idempotency & job-status protocol | [`docs/runbooks/worker-idempotency.md`](../runbooks/worker-idempotency.md) |
|
|
|
|
## What's next
|
|
|
|
→ [04 — MCP Integration](./04-mcp-integration.md) covers how the Claude agent drives this workflow from the queue side.
|