ADR 0015: Rebase-First Git Flow

Status: Accepted
Date: 2026-04-14
Deciders: Ideony team

Context

Ideony is built by a small team (2–3 devs). The default git pull creates merge commits, producing a noisy history that is hard to bisect and review. A clean linear history is preferred for a project where git log and git bisect are regular debugging tools.

Decision

Configure the repo for rebase-first integration: pull.rebase=true and branch.autosetuprebase=always at the repo level (.git/config). git pull (and git pull --rebase) is the default for syncing main. git merge is reserved exclusively for the hotfix-to-prod workflow once a production release branch exists. Direct pushes to main are the norm during MVP 0 (no PR gate, per skip-pr-during-mvp0 policy); PRs re-enabled after v0 ship.

Consequences

Linear commit history on main — git log --oneline is readable, git bisect is effective.
No accidental merge commits from routine git pull on a shared branch.
Conventional commits (feat:, fix:, refactor:, etc.) remain meaningful in a linear log.

Rebase rewrites commit SHAs — force-push to feature branches required after upstream rebase; team must be aware.
Merge conflicts surface at rebase time rather than merge time; unfamiliar developers may find rebase conflict resolution harder.
git merge reserved policy requires discipline; accidental merges on main would break linear history.

Alternatives considered

Default merge flow — rejected: merge commits from git pull pollute history; hard to bisect; git log becomes hard to read with 3+ contributors.
GitHub Flow with squash merges — considered for post-MVP PR workflow; squash collapses feature branch into one commit, losing intermediate atomic commits. Revisit after v0.
GitFlow (main + develop + release branches) — rejected: overkill for a 2-3 person MVP team; adds ceremony without benefit at this stage.