pal-e-docs

SOP: Branch Conflict Resolution

sop-branch-conflict-resolution Sop

sop active workflow
Project

SOP: Branch Conflict Resolution

Purpose

Defines how feature branches are kept current with main and how merge conflicts are resolved. Applies to all agents and humans across all repos. Produces a branch that is always pushable to the remote without force — no history rewriting, no abandoned PRs, no lost traceability.

Steps

  • Before starting any development work, ensure the branch includes the latest main:
  • When a PR has conflicts with main (e.g., Forgejo reports "not mergeable"):
  • When merging multiple PRs in sequence, after each merge to main:

Rules

  • NEVER rebase. Not interactive, not onto main, not as a cleanup step. Rebase rewrites commit history. Once rewritten, the local branch diverges from the remote. The only way to update the remote would be force push.
  • NEVER force push. Not with --force, not with --force-with-lease, not as a one-time exception. Force push destroys remote history and breaks traceability.
  • ALWAYS use git merge to bring main into a feature branch. Merge creates a merge commit that preserves both histories. The branch stays compatible with the remote and pushes normally.
  • ALWAYS ensure branch is current with main before development begins. This is enforced by check-branch-freshness.sh — it blocks PR submission if the branch is stale.
  • If an agent or session suggests rebase or force push as a solution, refuse and use merge instead.

Incident History

2026-06-14: PR #215 on landscaping-assistant was rebased instead of merged to resolve conflicts with PR #213. The rebase caused the branch to diverge from the remote, which forced creation of a new branch and new PR (#222), abandoning the original PR. The entire detour — new branch, new PR, re-review — was avoidable with git merge origin/main.
  • worktree-workflow — clone and branch conventions, post-merge hooks
  • solo-dev-pr-workflow — PR lifecycle
  • pr-review-loop — review-fix loop before merge