Skip to content
Markdown

ADR 0001 — Trunk-based branching with squash-merge into main

  • Status: Accepted
  • Date: 2026-05-24
  • Deciders: @TheurgicDuke771

Context

DataQ v1 has an 8-week timeline and a small team (starting solo, expected to grow). We need a branching model that supports frequent integration, keeps main history readable, and aligns with the working-agreement of one functionality per commit.

Decision

Adopt trunk-based development with short-lived feature branches off main, and squash-merge as the only allowed merge method into main.

  • All work happens on a branch named feature/<desc>, fix/issue-<N>-<desc>, chore/<desc>, docs/<desc>, refactor/<desc>, or test/<desc>. The branch prefix matches the conventional-commit type of the eventual PR title (see ADR 0002 for the full allowed type set).
  • Branches are short-lived (ideally hours to a couple of days), opened as PRs against main.
  • PRs are squash-merged — the PR title becomes the single commit on main (so PR titles MUST follow conventional commits — see ADR 0002).
  • No long-lived develop branch.
  • main is protected via a GitHub ruleset (deletion blocked, force-push blocked, linear history required, PR required, squash-only merge, dismiss stale reviews on new push). Admin (sole maintainer) can bypass in emergencies.
  • Auto-delete head branches on merge.

Consequences

Positive - main history reads as one commit per delivered functionality — matches working-agreement #1. - Short-lived branches force small, reviewable changes. - No long-lived branches to keep in sync. - Linear history makes git bisect reliable.

Negative - Loses individual WIP commits inside a PR. Mitigated: those commits remain visible in the PR view on GitHub. - Solo dev currently has required_approving_review_count: 0 — must bump to 1 when a second contributor joins (tracked as a future change).

Alternatives considered

  • GitFlow — rejected. The develop / release / hotfix overhead is unjustified for an 8-week single-tenant v1; release cadence is continuous, not versioned.
  • Merge commits preserving branch history — rejected. Squash gives one commit per functionality on main; preserved branch history would dilute that signal and clutter git log.
  • Rebase-and-merge — rejected. Preserves all WIP commits on main, breaking the one-functionality-per-commit principle.