Skip to content

docs(pr-flow): catch up and re-test before merging when v2/main moved - #5616

Open
cliffhall wants to merge 2 commits into
v2/mainfrom
v2/docs/5589-pr-flow-catch-up-before-merge
Open

cliffhall wants to merge 2 commits into
v2/mainfrom
v2/docs/5589-pr-flow-catch-up-before-merge

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #5589

Description

Adds the rule and the recipe for catching a PR up before it merges when v2/main moved under it.

  • AGENTS.md (Issue-driven work style): one new rule. Before a PR merges, it is caught up and re-tested if v2/main moved in a way that can interact with it. "No conflicts" is not that test. What landed can interact when it touches a src/<server>/ directory the PR also touches, or when either side touches repository-wide configuration (a root manifest, lockfile or configuration file, scripts/, .github/workflows/). In doubt, re-test. Catching up is a merge of origin/v2/main, never a rebase, then the gate, a push and green CI on the new head.
  • pr-flow step 10: now split into "Before the merge" and "After the merge". The new part holds the commands that list what the PR's head lacks and run the two checks, the decision table, the catch-up (merge, npm install, gate, push, one backgrounded gh pr checks --watch), the statement that a conflict-free catch-up needs no new Copilot round, and the fan-out note (a PR changing a server's configuration merges last, or the others are re-tested after it) with the query that lists the open PRs touching a server.
  • pr-flow step 6 pointed at "step 9" for the manual close; the close-out is step 10. Corrected, since the new text cites step numbers next to it.
  • One new trigger eval case for the step. The skill's description is unchanged.

Server Details

None (repository-wide): AGENTS.md and the pr-flow skill.

Motivation and Context

#5569: #5564 and #5567 were each gated and CI-green against a base that lacked the other, GitHub reported the second as cleanly mergeable, and the combination failed ruff check on v2/main. CI here runs on push, on the branch's head commit, so nothing had tested the combined tree.

Relation to #5588 (a merge queue or required status checks for v2/main, a maintainer decision): this procedure is what holds until that is decided.

  • A merge queue would make the whole "Before the merge" section redundant: the queue builds and tests the combined tree. The section and the AGENTS.md rule would be removed with that change.
  • Required checks with "require branches to be up to date" would make the decide half redundant (GitHub would demand a catch-up after every merge, interacting or not); the catch-up commands would stay.
  • Required checks without the up-to-date requirement, or no change, leave this step as written.

How Has This Been Tested?

No client-observable surface; targeted probes instead.

The recipe replayed against the incident. HEAD_SHA is #5567's head (31a72754), and the base tip is v2/main right after #5564 merged (88af1edb), which is the state #5567 was merged into:

log: 88af1edb Merge pull request #5564 from modelcontextprotocol/v2/fix/5557-fetch-pin-checked-address
log: e961a061 fix(fetch): close a won connection when cancelled during the race's teardown
...
A:
src/fetch/
B:

Check A names src/fetch/, so the table says catch up; the catch-up's gate would have failed ruff check before the merge. Controls: a head already at origin/v2/main, and #5596's head against the tip it merged into, both print no commits and nothing for A or B.

Fan-out query: run against the live repo with src/fetch/; returns the open PRs touching that server.

Skill checks:

  • npm run verify:skills: OK, 11 skills, listing share 3903/4000 (unchanged, the description did not change).
  • npm run skills:eval -- pr-flow (RUNS=3): 9/9 cases at 100%, including the new one ("My PR is green and GitHub says it has no conflicts, but another PR for the same server merged into v2/main ten minutes ago. What do I have to do before it can merge?") and both negatives. Only pr-flow's cases were run, not the whole suite, because no description changed.
  • No $0–$9 or $ARGUMENTS in the body.
  • npm run local:gate: exit 0.

Breaking Changes

None.

Types of changes

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation (not applicable: no protocol surface)
  • My changes follow MCP security best practices (not applicable: documentation only)
  • I have updated the server's README accordingly (not applicable: no server changed)
  • I have added a changeset (not applicable: nothing a TypeScript server publishes changed)
  • I have tested this with an LLM client (not applicable: no server-facing change; the skill's trigger evals ran instead)
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling (not applicable)
  • I have documented all environment variables and configuration options (not applicable)

🤖 Generated with Claude Code

AGENTS.md gains the rule: a PR is caught up and re-tested before it merges
when v2/main moved in a way that can interact with it, with a definition of
"can interact" that is cheap to check. pr-flow step 10 gains the recipe:
list what the PR's head lacks, decide, merge origin/v2/main into the branch,
gate, push, wait for CI, plus the fan-out ordering note.

Also corrects step 6's pointer to the close-out step (9 -> 10) and adds a
trigger eval case for the new step; the description is unchanged.

Closes #5589

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall cliffhall added the v2 label Nov 18, 2026
@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: bba0b99

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documented command block runs git push even when the validation gate fails, allowing a failing combined tree to be pushed contrary to the pre-push rule.

1 open issue
What changed in this PR

Adds a pre-merge catch-up procedure for PRs affected by changes on v2/main, addressing the integration failure described in #5589 without changing repository rulesets or server behavior.

Changes:

  • Defines when upstream changes require merging the latest base and re-testing.
  • Documents catch-up commands, CI waiting, review expectations, and ordering for related PRs.
  • Adds a skill trigger evaluation and corrects the close-out step reference.
File Description
AGENTS.md Adds the rule for catching up and re-testing interacting changes before merge.
.claude/​skills/​pr-flow/​SKILL.md Adds the pre-merge procedure and corrects the close-out reference.
.claude/​skills/​pr-flow/​evals/​evals.json Adds a trigger case for a green PR whose base has changed.

Review effort: Balanced

Comment thread .claude/skills/pr-flow/SKILL.md Resolved
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: one finding, fixed.

  • Push ran even when the gate failed (pr-flow step 10, the catch-up block): fixed in bba0b99. The block now ends in npm run local:gate && git push, and the bullet below it states that a red gate pushes nothing.

No suppressed comments. Gate exit 0 on bba0b99. Requesting round 2.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the pre-merge catch-up and re-testing documentation changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 2: clean (approval recommended, no open issues; the round 1 finding shows as resolved). The loop ends here on the clean-round exit.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

pr-flow: catch up and re-test before merging when v2/main moved under the PR

2 participants