FLOW-005 critical Merge Strategy

Merge strategy preserves history

Regular merges used, no squash/rebase that loses history

Question to ask

"Could you trace exactly what changed in your last release?"

What to check

  • allow_merge_commit enabled
  • Squash merge disabled or used sparingly
  • Merge commits show full history preserved
  • No force-pushes to protected branches

Verification guide

Severity: Critical

Check automatically:

  1. Check repo merge settings:

    # Get allowed merge strategies
    gh api repos/{owner}/{repo} --jq '{allow_squash_merge, allow_merge_commit, allow_rebase_merge}'
    
  2. Sample recent merge commits:

    # Check merge commits on main
    git log main --oneline --merges -10
    
    # Check merge commits on staging
    git log staging --oneline --merges -10 2>/dev/null
    
  3. Detect squash merges (single commit referencing PR):

    # Squash merges appear as single commits with (#123) reference but no merge commit
    git log main --oneline --no-merges -20 | grep -E "\(#[0-9]+\)$"
    
  4. Check staging→main relationship:

    # See if branches are in sync or diverged
    git log main..staging --oneline 2>/dev/null | head -5
    git log staging..main --oneline 2>/dev/null | head -5
    
  5. Look for force-pushes (if reflog accessible):

    # Check reflog for forced updates
    git reflog show main --oneline -20 2>/dev/null | grep -i "forced"
    

Cross-reference with:

  • GIT-004/005 (Branch protection) - protection rules may enforce merge strategy
  • FLOW-001 (Feature branch workflow) - merges should come from PRs

Pass criteria:

  • Regular merge commits enabled (allow_merge_commit: true)
  • Squash merge disabled OR used sparingly
  • Recent merges show merge commits with full history preserved
  • No evidence of force-pushes to protected branches

Fail criteria:

  • Squash-only merges (history lost)
  • Rebase merges rewriting shared history
  • Evidence of force-pushes after merge
  • Git history shows orphaned/dangling commits

If squash enabled, ask user: "Squash merge is enabled. Is this intentional? Squashing loses individual commit history from PRs. The recommended approach is regular merge to preserve history, with history cleanup done in the branch before merging."

Evidence to capture:

  • Repo merge settings (which strategies allowed)
  • Sample merge commits showing preserved history
  • Count of squash merges vs regular merges
  • Any evidence of force-pushes or history rewrites

Section

09. Development Workflow

Monitoring & Health