PR Merge

The procedure

REMOTE is origin here. TARGET is the branch being merged into, ASKED the PR's base branch; they differ only when retargeting.

1. Preconditions. The working tree is clean for tracked files (git status --porcelain --untracked-files=no prints nothing). Start the CI gate check in the background now.

2. Update the branches. The local branch must not have diverged:

   git fetch $REMOTE
   git checkout $TARGET && git merge --ff-only $REMOTE/$TARGET
   # when retargeting, the same for $ASKED

3. Fetch the PR head into a local pull/<N> branch:

   git fetch -f $REMOTE refs/pull/$N/head:pull/$N

4. Squash when warranted. A multi-commit PR from a single contributor is squashed by default (branch-update merge commits made through the GitHub UI do not count as a second contributor). A multi-author PR is merged unsquashed to keep each author's commits, unless the commits carry no meaning and the user agrees to squash across authors. A PR that contains merge commits cannot be merged unsquashed: squash it, or rebase the merge commits away first. The squashed commit keeps the first commit's author and author date, and takes the PR title as its message:

   git checkout pull/$N
   base=$(git merge-base $ASKED pull/$N)   # the PR is still based on $ASKED at this point
   first=$(git rev-list $base..pull/$N | tail -1)
   last=$(git rev-list $base..pull/$N | head -1)
   author=$(git log -1 --format='%an <%ae>' $first)
   date=$(git log -1 --format=%ad $first)
   git reset --hard $first~
   git merge --squash $last
   git commit -m "$PR_TITLE" --author="$author" --date="$date"

5. Retarget when merging into another branch than the PR asked:

   git rebase --onto $TARGET $ASKED pull/$N

   Remember that retargeting is a rewrite, not a copy: the review skill's rules on expressing the fix in the target branch's shape apply.

6. Build the message from the template above and write it to a file. Generate the Commits section now, from the final shas: git -c color.ui=false log $TARGET..pull/$N --oneline.

7. Merge without committing:

   git checkout $TARGET
   git merge --no-ff --no-commit pull/$N

8. Commit with the prepared message: git commit --file=<message file>.

9. Attach the notes (skip for security merges and comment-less PRs):

   git fetch -f $REMOTE refs/notes/github-comments:refs/notes/github-comments
   git notes --ref=github-comments add --file=<notes file>

10. Validate. Run the test suites of the touched components (./phpunit src/Symfony/Component/<Name>) whenever the merge involved a rebase, a squash with conflicts, or anything beyond what CI already ran.

11. Stop for the single confirmation described at the top: present the summary, collect the CI verdict from the background check, and get one go-ahead for everything that follows.

12. Sync the PR on GitHub when the head was rewritten (squashed or retargeted), before the upstream push, so GitHub can mark the PR merged instead of closed. Only possible when the PR allows maintainer edits; otherwise skip, and the PR will show as closed. When retargeted, change the PR base first (gh pr edit $N --base $TARGET), then force-push the rewritten head to the contributor's fork, guarded by the head SHA the PR had:

    git push --no-follow-tags --force-with-lease=$HEAD_BRANCH:$OLD_HEAD_SHA $FORK_SSH_URL pull/$N:$HEAD_BRANCH

    This is the only force-push in the whole process, and it never targets the upstream repository. If it fails, restore the PR base.

13. Clean up and push:

    git branch -D pull/$N
    git push --no-follow-tags $REMOTE $TARGET refs/notes/github-comments

    Leave refs/notes/github-comments out when no note was added.

14. Close the loop on GitHub. Thank the author with a one-line comment (skip when the merger authored the PR, or for bots). Close the linked issues: the Issues row of the PR header table (Fix #NNNNN) and closing keywords in the body name them. GitHub auto-closes them only when the merge lands in the default branch, which is the dev branch here; a merge into any other branch leaves them open, so close each one with a short comment naming the PR and branch that fixed it. For a feature merged into symfony/symfony, open an issue on symfony/symfony-docs, milestoned to the target version, linking the PR and its authors, unless the PR body already links a real docs PR.

Conflicts and amending

• To amend the PR before merging (a review fix, a changelog line), pause after step 5 on the pull/<N> branch, amend there, then continue with step 6.
• When step 7 conflicts and the PR is editable, abort the merge and rebase pull/<N> onto the target instead: conflicts get resolved in the PR's own commits, and the recorded merge stays conflict-free. Then redo step 7.
• When the PR is not editable, resolve inside the merge by hand and continue.
• Amendments follow pr-review-merge-prep: keep the contributor's authorship, amend into their commits, never a placeholder identity.

Verify before pushing

git show -s --format=%B HEAD                        # message matches the template, category exact
git log -1 --format='%an <%ae> / %cn <%ce>' HEAD    # merger as author and committer of the merge commit
git log --first-parent --oneline $REMOTE/$TARGET..$TARGET   # exactly one new first-parent commit
git notes --ref=github-comments show HEAD           # notes attached, when expected

The inner commits must keep the contributor as author. The committer of rewritten inner commits is the merger; that is expected.

Hard rules

• Never force-push to the upstream remote, never rewrite the target branch. A merge adds exactly one merge commit on top of it.
• Never merge with a plain git merge: without the prepared message, the archive value of the commit is lost and tooling cannot classify it.
• Never push with --follow-tags; local tags stay local.
• Never decide an override (a PR-caused CI failure, missing votes, an unmaintained branch, a milestone mismatch, an unsquashable PR) without asking; surface it in the pre-push summary.