61 lines
2.5 KiB
Markdown
61 lines
2.5 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-05-03
|
|
decision-makers: [janpetervisser]
|
|
---
|
|
|
|
# ADR-0003: One branch per milestone, push only after user test
|
|
|
|
## Context and Problem Statement
|
|
|
|
Every `git push` to a feature branch triggers a Vercel preview deployment. On the Hobby plan, preview builds are limited and cost money. How should we structure branches and pushes to minimize preview-build spend while still supporting a fast AI-driven development loop?
|
|
|
|
## Decision Drivers
|
|
|
|
- Vercel Hobby plan: preview builds are finite and billed per deployment.
|
|
- Small team (primarily solo developer + AI agent): branch overhead should be minimal.
|
|
- AI-driven flow: the agent commits frequently in small logical layers; we don't want a push per commit.
|
|
- User acceptance is done interactively per milestone, not per story.
|
|
|
|
## Considered Options
|
|
|
|
- **Branch per story** — one branch per story, PR per story.
|
|
- **Branch per milestone** — one branch for all stories in a milestone, single PR after user test.
|
|
- **Trunk-based development** — commit directly to `main` with feature flags.
|
|
|
|
## Decision Outcome
|
|
|
|
Chosen option: **Branch per milestone**, because it is the only option that keeps preview-build count proportional to milestones (not stories), while still enabling isolated review via a single PR.
|
|
|
|
### Consequences
|
|
|
|
- Good, because preview deployments are rare — only one per milestone reaching review.
|
|
- Good, because PR history maps to milestones, not micro-stories.
|
|
- Bad, because branches live longer; merge conflicts are larger but less frequent.
|
|
- Bad, because a single failed story blocks the milestone PR.
|
|
|
|
### Confirmation
|
|
|
|
Before pushing, the developer/agent must confirm explicitly. `git push` is never automated. See `docs/runbooks/branch-and-commit.md`.
|
|
|
|
## Pros and Cons of the Options
|
|
|
|
### Branch per story
|
|
|
|
- Good, because small, focused PRs are easy to review.
|
|
- Bad, because each push triggers a preview build — N stories = N builds per milestone.
|
|
|
|
### Branch per milestone
|
|
|
|
- Good, because minimal preview builds.
|
|
- Good, because the PR represents a coherent feature set.
|
|
- Bad, because long-lived branches.
|
|
|
|
### Trunk-based development
|
|
|
|
- Good, because no branch management overhead.
|
|
- Bad, because requires feature flags to hide incomplete work — too much infrastructure for this scale.
|
|
|
|
## More Information
|
|
|
|
Revisit this decision if/when the Vercel account upgrades to Pro (unlimited preview builds). At that point, branch-per-story is the preferred default. Update `docs/runbooks/branch-and-commit.md` and this ADR when that happens.
|