ADR-001: Use the environment-branch model instead of trunk-based development

Status

Accepted — 2026-06-06 (ratified by Nikola Jeremić during standards review)

Context

Industry consensus (Fowler's branching patterns, Atlassian, DORA research) favors trunk-based development with a single main and short-lived branches; our own initial draft of the Git standard proposed it. However, ExpertGroup operates many small-team services where releases are promoted deliberately through test environments, and the team wants the branch state itself to answer "what is running where" — a property trunk-based models delegate to deployment tooling we don't have yet.

Decision

We will use three long-lived environment branches — development (default) → staging → production — with feature branches squash-merged into development and promotions done via plain-merge PRs (never squash, to keep histories converging). Staging auto-deploys on merge; production deploys after environment approval and is tagged vX.Y.Z. Trunk-based development was considered and rejected for now because environment visibility and promotion control outweigh merge-frequency benefits at our current team size and tooling maturity.

Consequences

Easier: knowing what runs in each environment from git alone; controlled, reviewable promotions; hotfix path is explicit. Harder: we accept the known risks Fowler warns about — promotion merge conflicts if plain-merge discipline slips, unfinished work riding promotions (mitigated by feature flags, see expert-review item 4), and slower integration than trunk-based. If deployment tooling matures (artifact promotion with full traceability), this ADR should be revisited and may be superseded.