From 24b8f86ccabde6f37045f3ec5e54c86d7d8d2338 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 12:56:45 -0500 Subject: [PATCH 1/2] docs(pr-flow): catch up and re-test before merging when v2/main moved 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 Signed-off-by: cliffhall --- .claude/skills/pr-flow/SKILL.md | 104 +++++++++++++++++++++++- .claude/skills/pr-flow/evals/evals.json | 4 + AGENTS.md | 13 +++ 3 files changed, 120 insertions(+), 1 deletion(-) diff --git a/.claude/skills/pr-flow/SKILL.md b/.claude/skills/pr-flow/SKILL.md index e64ac106dc..2c7f41e99b 100644 --- a/.claude/skills/pr-flow/SKILL.md +++ b/.claude/skills/pr-flow/SKILL.md @@ -252,7 +252,7 @@ gh pr view "$PR" --repo modelcontextprotocol/servers \ ``` The link does **not** make the issue close on merge into `v2/main`; that is -still done by hand in step 9. +still done by hand in step 10. Then move the card to **In Review** (`/board-ops`). The PR itself never goes on the board. @@ -407,6 +407,108 @@ the PR shows why the loop ended. Merging is a maintainer's decision. Do not merge on your own initiative. +### Before the merge: catch up if `v2/main` moved + +The rule is in `AGENTS.md` **Issue-driven work style**: a PR is caught up and +re-tested before it merges when `v2/main` moved in a way that can interact +with it. CI here runs on **push**, on the branch's head commit, and the gate +ran in your worktree, so neither has seen anything that landed on `v2/main` +after the branch last took it in. GitHub's "no conflicts with the base branch" +compares text and tests nothing: #5564 and #5567 were each green and cleanly +mergeable, merged ten minutes apart, and left `v2/main` failing `ruff check` +(#5569). + +**1. List what the PR's head lacks.** From any checkout of this repo: + +```sh +PR= +git fetch origin v2/main "refs/pull/$PR/head" +HEAD_SHA=$(gh pr view "$PR" --repo modelcontextprotocol/servers \ + --json headRefOid --jq .headRefOid) + +# Commits on v2/main that the head does not hold. Nothing printed: the PR was +# tested on the current tip, so there is nothing to catch up. +git log --oneline "$HEAD_SHA..origin/v2/main" + +# The files each side changed since the two diverged. +LANDED=$(git diff --name-only "$HEAD_SHA...origin/v2/main") +MINE=$(git diff --name-only "origin/v2/main...$HEAD_SHA") + +# Check A: servers that both sides touched. +comm -12 <(grep -oE '^src/[^/]+/' <<<"$LANDED" | sort -u) \ + <(grep -oE '^src/[^/]+/' <<<"$MINE" | sort -u) + +# Check B: repository-wide configuration, on either side: a root manifest, +# lockfile, config file or dotfile, scripts/, or a workflow. +WIDE='^([^/]+\.(json|js|mjs|cjs|ts|toml|ya?ml)|\.[^/]+|scripts/.*|\.github/workflows/.*)$' +grep -E "$WIDE" <<<"$LANDED" | sed 's/^/landed: /' +grep -E "$WIDE" <<<"$MINE" | sed 's/^/mine: /' +``` + +**2. Decide.** + +| The listing shows | Then | +| --- | --- | +| No commits | Nothing to do. Merge on green CI | +| Commits, and checks A and B both print nothing | What landed cannot interact with the PR. No catch-up needed | +| Check A prints a server, or check B prints any path | **Catch up** (below) | +| Anything you are unsure of | **Catch up**. The checks are deliberately coarse, and a gate run is cheaper than a red `v2/main` | + +A server's own configuration (`pyproject.toml`, `uv.lock`, `tsconfig.json`, +`vitest.config.ts`) is inside its directory, so check A covers it: that is the +#5569 case, where a `requires-python` bump changed which lint rules applied to +code another PR was adding. + +**3. Catch up**, in the PR's worktree: + +```sh +git fetch origin v2/main +git merge --no-edit origin/v2/main +npm install # the merge may have moved package-lock.json +npm run local:gate; echo "EXIT=$?" +git push +``` + +- **Merge, never rebase.** A rebase rewrites the commits that were reviewed, + outdates every review thread and needs a force-push. The merge commit is + exempt from the DCO check (step 3). +- **The gate runs on the merged tree before the push**, as before any push + (step 4). A red stage here is the interaction this step exists to find: fix + it on the branch, signed off, and run the gate again. +- **Then wait for CI on the new head**, with one backgrounded command, as + `AGENTS.md` **Waiting on long-running work** says. The `sleep` gives the push + runs time to register; `--watch` on a head with no checks yet exits at once. + + ```sh + sleep 60; gh pr checks "$PR" --repo modelcontextprotocol/servers \ + --watch --interval 30; echo "EXIT=$?" + ``` + +- **A catch-up that merged without conflicts and passed the gate unchanged + needs no new Copilot round.** Nothing the PR adds changed. One that needed a + conflict resolved or a fix pushed changed the PR, so request a round (step 9). +- **If `v2/main` moves again before the merge, run step 1 again.** It costs + one fetch, and most of the time it prints nothing that interacts. + +**Fan-outs.** When several PRs for one server are open at once, a PR that +changes that server's **configuration** (a language floor, lint or compiler +settings, a dependency major) interacts with every one of them. Merge it +**last**, after catching it up on the others, or merge it first and catch up +and re-test each of the others after it. The open PRs that touch a server: + +```sh +gh pr list --repo modelcontextprotocol/servers --base v2/main --state open \ + --limit 200 --json number,title,files \ + --jq '.[] | select(any(.files[]; .path | startswith("src/fetch/"))) + | "\(.number) \(.title)"' +``` + +Nothing enforces this step: `v2/main`'s ruleset requires no status checks, so +it is done by hand by whoever merges. Whether a merge queue or a required +up-to-date check should take it over is #5588. + +### After the merge + **On merge into `v2/main`, close the issue by hand and move its card to Done**, since auto-close does not fire there: diff --git a/.claude/skills/pr-flow/evals/evals.json b/.claude/skills/pr-flow/evals/evals.json index 2fa6dacb38..e47e1011f5 100644 --- a/.claude/skills/pr-flow/evals/evals.json +++ b/.claude/skills/pr-flow/evals/evals.json @@ -23,6 +23,10 @@ "prompt": "My PR into v2/main just merged. What do I still need to do to close it out?", "expect": "pr-flow" }, + { + "prompt": "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?", + "expect": "pr-flow" + }, { "prompt": "What does this regex match? /^[a-z]+$/", "expect": null diff --git a/AGENTS.md b/AGENTS.md index c090e1a5d0..56236ab87c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -600,6 +600,19 @@ here. declined finding that is worth doing gets its own issue, linked in the reply. The rule is under [Responding to code reviews](#responding-to-code-reviews). +- **Before a PR merges, it is caught up and re-tested if `v2/main` moved in a + way that can interact with it.** GitHub reporting no conflicts is not that + test: it compares text, and the gate and CI ran on the PR's head, which + holds nothing that landed on `v2/main` after the branch last took it in. Two + fetch PRs that were each green left `v2/main` red that way (#5569). What + landed **can interact** when it touches a server directory + (`src//`) the PR also touches, or when either side touches + repository-wide configuration: a root manifest, lockfile or configuration + file, `scripts/`, or `.github/workflows/`. When in doubt, re-test. Catching + up is a merge of `origin/v2/main` into the branch, never a rebase, then the + gate, a push, and green CI on the new head. `v2/main`'s ruleset requires no + status checks, so this is on whoever merges. The recipe is the `pr-flow` + skill (step 10). - **If new tasks are discovered during development, create issues** for them and put them on the board, rather than widening the current PR. From bba0b99a8d745846b28eadeed77eee2c8d79c148 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 13:43:30 -0500 Subject: [PATCH 2/2] docs(pr-flow): push the catch-up only when the gate passes Co-Authored-By: Claude Fable 5.2 Signed-off-by: cliffhall --- .claude/skills/pr-flow/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/skills/pr-flow/SKILL.md b/.claude/skills/pr-flow/SKILL.md index 2c7f41e99b..0c37bd0f4d 100644 --- a/.claude/skills/pr-flow/SKILL.md +++ b/.claude/skills/pr-flow/SKILL.md @@ -465,16 +465,16 @@ code another PR was adding. git fetch origin v2/main git merge --no-edit origin/v2/main npm install # the merge may have moved package-lock.json -npm run local:gate; echo "EXIT=$?" -git push +npm run local:gate && git push # the push runs only on a green gate ``` - **Merge, never rebase.** A rebase rewrites the commits that were reviewed, outdates every review thread and needs a force-push. The merge commit is exempt from the DCO check (step 3). - **The gate runs on the merged tree before the push**, as before any push - (step 4). A red stage here is the interaction this step exists to find: fix - it on the branch, signed off, and run the gate again. + (step 4), and a red gate pushes nothing. A red stage here is the interaction + this step exists to find: fix it on the branch, signed off, and run that + last line again. - **Then wait for CI on the new head**, with one backgrounded command, as `AGENTS.md` **Waiting on long-running work** says. The `sleep` gives the push runs time to register; `--watch` on a head with no checks yet exits at once.