Git PR Merging Strategy (Draft)

Draft: This document is under discussion and may change. Treat it as guidance, not policy, until formally adopted.

This document defines how we open, review, and merge pull requests across our repositories.

Principles

  • Every change goes through a pull request.
  • Keep history readable and intentional.
  • A clean git log should tell the story of the codebase without merge noise.
  • Developers are free to work however they want on their branch, but merges to master follow a strict standard.

The intent is to keep collaboration disciplined and auditable while still giving developers freedom on their branch. It also ensures that the project history stays readable and useful for debugging and audits.

Branching

  • Use short, descriptive branch names based on type and ticket when available.
  • Preferred format: <type>/<ticket>-<slug> (for example, feat/123-foo).
  • Optional author suffix if needed: <type>/<ticket>-<slug>-<author> (for example, feat/123-foo-alice).

The format keeps branches easy to scan and tie back to work items, while keeping the ticket visible and the intent clear in PR lists and tooling.

Pull Request Requirements

  • Clear title and description that explains the why, not just the what.
  • Link to any relevant ticket, issue, or incident.
  • Keep PRs small and focused; split when scope expands.

Clear requirements reduce review time and preserve context for future readers. They also make it easier to trace changes back to user needs or incidents, and help avoid oversized PRs that are hard to review safely.

Review Requirements

  • At least one approving review is required.
  • Address all comments or explicitly resolve with reviewer agreement.
  • No self-merge without approval.
  • Repo rules must enforce required reviews before merge.

The goal is to ensure changes are independently reviewed, align with ISO expectations for controlled change, and prevent silent merges without oversight.

Merging

  • We use squash and merge only.
  • No merge commits or rebase merges.
  • The squash commit is the canonical record of the change.

We use squash-only merges so each PR becomes a single, narrative change in git log. This avoids merge commits, branch remnants, and mid-flight work-in-progress commits, and keeps review focused on the PR rather than on commit choreography.

Squash Commit Standards

  • Use a short, imperative summary that describes the user- or system-visible outcome.
  • Add context in the body if the change is non-obvious.
  • Treat the squash commit message as the durable project history.

The squash commit is the only one that survives in main/master, so it must stand on its own. Clear summaries keep git log useful for debugging and incident follow-ups.

CI and Checks

  • All required checks must pass before merging.
  • Flaky tests must be fixed or quarantined before merge. Do not merge while any required check is failing.
  • Repo rules must enforce that merges are blocked when required checks fail.

"Quarantine" means isolating the test so it does not run in required CI (for example, moving it to a non-blocking job or marking it as quarantined in the test runner).

Conventional Commits (Distant Future Option)

  • If we ever adopt Conventional Commits, it will apply to the squash commit only.
  • This keeps compliance simple and encourages narrower, more reviewable PRs.
  • The change type in the title (e.g., feat, fix, chore) naturally discourages mixing unrelated work.

A single, enforceable commit can drive changelog automation without forcing developers to curate their entire branch history. It also nudges PRs toward a single, coherent change, which makes reviews faster and reduces scope creep.