A project here typically spans several independent git repositories (e.g. the
Expenses ecosystem: expenses backend, expenses-web, expenses-admin, plus
this dev-handbook). Work needs a predictable path from “in progress” to “released to production”,
with a clear integration point and a production branch whose history is only
ever well-tested merges. Committing straight to a shared branch loses the
ability to gate integration and makes releases hard to reason about.
Decision
Every repo follows the same three-step branching flow:
feature/* → develop → main
feature/* — all active development; branched off develop before
any file is edited. Commit freely here.
develop — integration branch; only receives --no-ff merges from tested
feature branches, after the user explicitly approves.
main — production; only receives --no-ff merges from a release/*
branch at release time. Tags live on main.
Releases go through a release/vX.Y.Z branch cut from develop: bump the
version (pom.xml for a Java backend; package.json + lock for a frontend — each
repo’s version file is declared in the workspace handbook.json manifest), merge --no-ff into main and tag, then merge --no-ff back into develop, delete
the release branch, and push develop main --tags together. The /release
skill automates this. Bump is MINOR if any feat: commit exists since the
last tag, otherwise PATCH.
Rules that follow (mechanics):
Never commit directly to develop or main.
Each repo has an independent version history — versions need not match.
A breaking wire-contract change releases clients-first. Independent versions
mean nothing sequences a cross-repo change except the plan. When a server change
alters a shape a deployed client already reads, every client ships before the
server, and that ordering is recorded in the ADR that owns the change — not left
in a branch name or a chat message. Server-first is safe only for a purely
additive change. The client that cannot be rolled back with a redeploy (a mobile
build in review) is the one that sets the pace.
Co-author footer on every AI-assisted commit, naming the assisting model: Co-Authored-By: Claude <model name> <noreply@anthropic.com>
The behavioral agreements layered on this flow — approval before any
commit/merge/release, branching both repos for cross-repo work,
recap-before-phase — live in 0003-collaboration-working-agreements (kept
there, not restated here).
Consequences
main is always a clean trail of release: vX.Y.Z merges; rollback = check
out the previous tag.
develop is the single “what’s next” truth the user gates on.
Slightly more ceremony per change (branch + two merges at release), accepted
in exchange for a legible production history.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
* 1cc22b7 merge: develop into main|\| * f84c2dd merge: docs/point-at-handbook-paths into develop| |\| | * 88fa34e docs: point at the project docs in their new handbook home| |/* | 18ac190 merge: develop into main|\|| * 4ce3f27 merge: fix/document-title-and-link-previews into develop| |\| | * a7f3c9b fix: the document title and description were still the portfolio's| |/
Every merge is --no-ff, which is why the shape is legible at all: each feature keeps a
visible bubble, so “what shipped together” survives in the graph instead of being flattened
into a line of unrelated commits.
The branch prefix carries intent — feature/, fix/, docs/ — and the merge subject
names the branch, so git log --merges alone reads as a changelog of units of work.
The rule that is easiest to break is the one this repo broke and then repaired: branch
before editing, not after. The design-system move above was made on main and had to be
moved onto a feature branch off develop before it could be committed. The handbook uses docs/* branches straight off main instead, because it has no develop — the shape
follows what a repo releases, not dogma.
Source: allsensis-web — the graph the rule produces