kavin525zhang/llm_reasoning_framework/pr-merge

PR Merge — Contributor-First Pull Request Integration

Merge external pull requests while maximizing original author attribution. Core principle: merge first, resolve conflicts after — never rewrite a contributor's work from scratch.

Core Principles

1. Preserve authorship — use gh pr merge --squash for clean PRs. For manual merges, use --author="Name <email>".
2. Merge first, fix after — accept the PR's approach even if it differs from local style. Fix conflicts in a separate commit.
3. Selective merge is OK — exclude files with --exclude when a PR contains features already implemented locally. Document what was excluded.
4. Never `git apply` + self-commit — this loses author attribution entirely.

Workflow

1. Triage Open PRs

gh pr list --repo OWNER/REPO --state open \
  --json number,title,author,additions,deletions,mergeable

Classify each PR: merge directly, merge with conflict resolution, selective merge, or close.

2. Merge Clean PRs via GitHub

Prefer gh pr merge — preserves author automatically:

gh pr merge NUMBER --repo OWNER/REPO --squash \
  --subject "feat: description (#NUMBER)"

3. Handle Conflicting PRs Locally

git fetch origin pull/NUMBER/head:pr-NUMBER
git merge pr-NUMBER --no-edit
# Resolve conflicts keeping both sides where possible
git add -A && git commit --no-edit

4. Selective Merge (Skip Some Files)

When a PR contains features already implemented locally:

gh pr diff NUMBER --repo OWNER/REPO | \
  git apply --exclude='path/to/skip.py' --exclude='CHANGELOG.md'
git commit --author="Author Name <author@email>" \
  -m "feat: description (#NUMBER)
 
Cherry-picked from PR #NUMBER. Excluded: file.py (already implemented)."

5. Close Duplicate/Superseded PRs

gh pr close NUMBER --repo OWNER/REPO \
  --comment "Fixed via PR #OTHER. Thank you for the contribution!"

6. Post-Merge Verification

python -m ruff check src/ tests/    # lint
python -m pytest tests/ -q          # unit tests
git push origin main                # push

Then run harness-eval for end-to-end verification on an unfamiliar codebase.

Attribution Checklist

Before pushing a merged PR:

• [ ] Original author appears in git log (via --author or GitHub squash merge)
• [ ] Commit message references PR number (#NUMBER)
• [ ] If selectively merged, commit body explains exclusions
• [ ] Closed PRs have a comment thanking the contributor
• [ ] Duplicate PRs acknowledge the contributor's investigation

Common Pitfalls

• git apply + self-commit loses author
• Rewriting from scratch instead of merging — merge their code, fix style after
• Force-pushing main after merge — may remove contributor commits
• Forgetting CHANGELOG conflicts — always exclude and handle manually
• Not testing after merge — clean merge doesn't mean working code

Additional Resources

Reference Files

• `references/merge-scenarios.md` — Detailed examples for each merge scenario (clean, conflicting, selective, duplicate)