ADR-0001: Trunk-Based Branching Model¶

Field	Value
Status	Accepted
Date	2026-05-21
Deciders	Arun Singh, Raja Choudhary, Rahul, Tushar
RFC	FLX-ENG-RFC-001

Context¶

As Flexli onboards more clients, the natural engineering drift is toward maintaining per-customer branches or forks. This path is fast for two or three clients and becomes the single largest source of merge debt and release risk at ten clients.

The team had a dev integration branch and short-lived feature branches with no formal protection or release process. There was no CI, no formal versioning, and no documented branching rules.

Decision¶

Adopt trunk-based development with main as the permanent trunk.

main is protected: no direct push; all changes via PR + green CI
feature/<id>-<slug> branches: hours to a few days; rebase on main daily
release/<version> branches: on-demand stabilisation windows; only fixes
hotfix/<id> branches: urgent production fixes from the release tag
No customer/<name>, dev, or environment branches

Rationale¶

Option	Why rejected
Keep `dev` integration branch	Long-lived `dev` diverges from `main`, creating integration risk and double-review overhead. RFC §4.2: "`main` is develop."
Per-customer branches	Merge debt grows quadratically with clients × features. Violates RFC design principle 1.
GitFlow (develop + release + hotfix)	Two permanent branches double the merge surface. Unnecessary for a small team with CI.
Trunk-based (chosen)	Lowest long-term merge cost; gives continuous integration; the simplest model that supports the RFC's release cadence

Consequences¶

Becomes easier: - Every merge to main can trigger a deployment — no "promote from dev" step - Release cuts are tags, not long-lived branches - Onboarding a new engineer has a clear mental model: one branch, short-lived features

Becomes harder: - Discipline required: features in progress must be behind feature flags if not ready to ship - Branch protection must be configured correctly before the team starts using main as trunk