docs: add PR conflict resolution guide and helper script#11060
Merged
Conversation
Add a "Resolving Conflicts in GitHub PRs" section to AGENTS.md with step-by-step instructions for force-fetching refs, rebasing, resolving lockfile conflicts, and verifying mergeability. Add shell/resolve-pr-conflicts.sh that automates the workflow: fetches metadata, force-updates the base ref, rebases, auto-resolves lockfile conflicts via pnpm install, force-pushes, and verifies the result. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation and a helper script to standardize how contributors resolve GitHub PR merge conflicts (with emphasis on force-fetch + rebase and pnpm lockfile regeneration) and to help verify GitHub’s mergeability state after updates.
Changes:
- Documented a step-by-step “Resolving Conflicts in GitHub PRs” workflow in
AGENTS.md. - Added
shell/resolve-pr-conflicts.shto automate force-fetching the base branch, rebasing, handlingpnpm-lock.yamlconflicts, force-pushing, and checking PR mergeability.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
shell/resolve-pr-conflicts.sh |
New automation script for conflict resolution (fetch/rebase/lockfile regen/push/mergeability check). |
AGENTS.md |
New documentation section describing the recommended manual procedure and pointing to the helper script. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Verify origin remote points to pnpm/pnpm before proceeding - Auto-checkout PR branch via gh if not already on it - Replace jq usage with gh --jq for consistency and fewer dependencies - Fail properly on rebase --continue instead of suppressing with || true Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The conflict resolution instructions in the Claude prompt used merge and plain fetch, which can produce stale refs and merge commits that GitHub still reports as conflicting. Updated to use force-fetch, SHA verification, and rebase with lockfile auto-resolution guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When manual conflict resolution is needed, the script now: - Prints MANUAL_RESOLUTION_NEEDED and lists the conflicted files - Exits so the agent can read the files, resolve markers, and git add - Agent then calls the script again with --continue to finish the rebase, force-push, and verify mergeability Also updates wt.fish prompt to instruct the agent on the --continue workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
shell/wt.fish:25
- This prompt now instructs running
resolve-pr-conflicts.sh, which force-pushes the rebased branch, but the final instruction in the same message says “Do NOT push.” That’s internally inconsistent and may cause the automation to either skip the script or violate the “no push” instruction. Consider clarifying that the only allowed push is the conflict-resolution force-push (or adjust the helper script/instructions to not push automatically).
3. Resolve any conflicts with the base branch by running './shell/resolve-pr-conflicts.sh $pr_number'. This force-fetches the base branch (avoiding stale refs), rebases, and auto-resolves lockfile conflicts. If it prints MANUAL_RESOLUTION_NEEDED, read the listed conflicted files, resolve the conflict markers, run 'git add' on each resolved file, then run './shell/resolve-pr-conflicts.sh $pr_number --continue' to finish the rebase and push. Do NOT skip this step. Do NOT assume the branch is up to date.
4. Address every review comment — fix the code as requested or as appropriate.
5. Look for any other bugs, issues, or style problems in the changed code and fix those too.
6. Run the relevant tests to verify your fixes work (check CLAUDE.md for how to run tests).
7. Give me a summary of what you found and what you changed, including any conflicts you resolved.
Do NOT push. Leave all non-merge changes unstaged for me to review."
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Stricter origin URL validation (match github.com[:/]pnpm/pnpm exactly) - Force-fetch with + prefix to handle non-fast-forward ref updates - Use --lockfile-only --ignore-scripts for lockfile regeneration - Move push remote detection after checkout; auto-add fork remotes Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.mdwith step-by-step instructions for resolving merge conflicts in PRs (force-fetching refs, rebasing, lockfile resolution, verifying mergeability)shell/resolve-pr-conflicts.shhelper script that automates the workflowMotivation
When resolving PR conflicts,
git fetch origin maincan return a stale ref, and merge commits can confuse GitHub's conflict detection. This documents the correct procedure (force-fetch + rebase) and provides a script to automate it.🤖 Generated with Claude Code