|
| 1 | +--- |
| 2 | +name: pr-flow |
| 3 | +description: "Take an issue through to a PR in this repo and close it out after merge. Use when asked to open, create or submit a PR; when naming a branch; when signing off commits or repairing a missing Signed-off-by; when recording client evidence for a PR; when requesting a Copilot review, answering its comments or deciding whether to run another round; or when closing out after a merge." |
| 4 | +disable-model-invocation: false |
| 5 | +--- |
| 6 | + |
| 7 | +# PR flow |
| 8 | + |
| 9 | +The rules this procedure carries out live in [`AGENTS.md`](../../../AGENTS.md) |
| 10 | +(**Contributing**, **Issue-driven work style**, **Responding to code reviews**, |
| 11 | +**Waiting on long-running work**). Board mechanics, including every board ID, |
| 12 | +are in `/board-ops`; creating a missing issue is `/issue-create`. This file names |
| 13 | +board columns and nothing else. |
| 14 | + |
| 15 | +**Pull requests against this repo are opened by the maintainers only.** Write |
| 16 | +access is not authorization to open one. Anyone else files a detailed issue |
| 17 | +(`/issue-create`) and a maintainer takes it from there. |
| 18 | + |
| 19 | +## 1. Start from an issue |
| 20 | + |
| 21 | +**Every PR closes an issue.** A PR with no linked issue has no board card, so |
| 22 | +the work is invisible to the board. If there is no issue yet, create one first |
| 23 | +with `/issue-create`; never open the PR and backfill. |
| 24 | + |
| 25 | +**Read the issue in full, every comment included.** Scope changes, maintainer |
| 26 | +decisions and "not this, that" corrections are usually in the comments, not the |
| 27 | +body: |
| 28 | + |
| 29 | +```sh |
| 30 | +gh issue view <N> --repo modelcontextprotocol/servers --comments |
| 31 | +``` |
| 32 | + |
| 33 | +Then assign it to yourself and move its card to **In Progress** (the |
| 34 | +move-a-card recipe in `/board-ops`): |
| 35 | + |
| 36 | +```sh |
| 37 | +gh issue edit <N> --repo modelcontextprotocol/servers --add-assignee @me |
| 38 | +``` |
| 39 | + |
| 40 | +## 2. Branch |
| 41 | + |
| 42 | +`v2/<type>/<N>-<slug>`, cut from **`origin/v2/main`**: |
| 43 | + |
| 44 | +```sh |
| 45 | +git fetch origin v2/main |
| 46 | +git switch -c v2/fix/4810-filesystem-symlink-escape origin/v2/main |
| 47 | +``` |
| 48 | + |
| 49 | +`<type>` follows the issue's type label: `bug` → `fix`, `enhancement` → `feat`, |
| 50 | +`documentation` → `docs`, `chore` → `chore`. The `v2/` prefix matches the base |
| 51 | +branch and keeps the work legible in `git branch -a` next to `main`. |
| 52 | + |
| 53 | +**Never cut from `main`.** It is the release line and does not carry `v2/main`'s |
| 54 | +history, so the PR diff would show unrelated changes. |
| 55 | + |
| 56 | +**Stacking.** When one issue's work depends on another PR that has not merged |
| 57 | +yet, branch from that PR's branch and open the PR with `--base` set to it. Say |
| 58 | +in the body that it is stacked and on which PR. When the lower PR merges, |
| 59 | +retarget the stacked one to `v2/main` (`gh pr edit <PR> --base v2/main`) and |
| 60 | +rebase it if GitHub reports conflicts. |
| 61 | + |
| 62 | +## 3. Sign off every commit (DCO) |
| 63 | + |
| 64 | +This repo adopted the [Developer Certificate of |
| 65 | +Origin](https://developercertificate.org/) (maintainer decision on #4861). |
| 66 | +Commit with **`git commit -s`**, every time. |
| 67 | + |
| 68 | +⚠️ **The [probot DCO app](https://probot.github.io/apps/dco/) is not installed on |
| 69 | +this repo yet**, so today nothing fails an unsigned commit. Installing it is an |
| 70 | +org-admin step (#4867). Sign off anyway: once the app is on, it checks |
| 71 | +every commit in a PR, so an unsigned commit pushed today becomes a red check |
| 72 | +that can only be cleared by rewriting history. Once the app enforces the check, |
| 73 | +`AGENTS.md` gains the signoff rule and this paragraph goes. |
| 74 | + |
| 75 | +What the app checks: each commit carries a `Signed-off-by: Name <email>` trailer |
| 76 | +whose name **and** email match the commit's author or its committer. Merge |
| 77 | +commits and bot-authored commits are exempt. There is no partial credit: one |
| 78 | +unsigned commit out of six fails the whole check. |
| 79 | + |
| 80 | +Two things that look like automation and are not: |
| 81 | + |
| 82 | +- ⚠️ **`git config format.signOff true` does nothing here.** Despite the name, |
| 83 | + it only defaults the `-s` flag for `git format-patch`. `git commit` never reads |
| 84 | + it, and there is no `commit.signoff` equivalent. |
| 85 | +- ⚠️ **A `prepare-commit-msg` hook works, but think before installing one.** The |
| 86 | + trailer is a certification, and a hook makes it on your behalf for _every_ |
| 87 | + commit, including work you merely cherry-picked. Inside that hook, |
| 88 | + `git var GIT_AUTHOR_IDENT` returns your config identity rather than the |
| 89 | + preserved author, so it cannot even tell it is signing for someone else. |
| 90 | + |
| 91 | +**Repairing commits already pushed** means rewriting them: |
| 92 | + |
| 93 | +```sh |
| 94 | +git rebase HEAD~<n> --signoff |
| 95 | +git push --force-with-lease |
| 96 | +``` |
| 97 | + |
| 98 | +Use `--force-with-lease` rather than `--force`, and rewrite only when you are the |
| 99 | +sole author and nobody has based work on the branch (a stacked PR above yours |
| 100 | +has). The two apparent alternatives are not alternatives: the app's empty |
| 101 | +"remediation commit" flow needs `allowRemediationCommits.individual`, and this |
| 102 | +repo ships no `.github/dco.yml`, so it is disabled; and the override button that |
| 103 | +anyone with write access sees only silences the check, with nobody certifying |
| 104 | +anything. |
| 105 | + |
| 106 | +The signoff is a DCO assertion made in **your own name**. It does not claim you |
| 107 | +wrote the code, so signing off a cherry-pick is legitimate. Fabricating |
| 108 | +_someone else's_ certification never is. |
| 109 | + |
| 110 | +## 4. Run the gate |
| 111 | + |
| 112 | +Run what CI runs for everything the change touches, and fix what fails before |
| 113 | +pushing: |
| 114 | + |
| 115 | +| Change touches | Command | |
| 116 | +| --- | --- | |
| 117 | +| Anything (always) | `npm run validate:guards` (CI's "Root guards" job: root format and lint, the coverage guards, `verify:skills`, the script tests) | |
| 118 | +| A TypeScript server | `npm run validate -w src/<server>` (format check, lint, typecheck, build, test) | |
| 119 | +| A Python server | `npm run validate:py -- <server>` (locked sync, ruff, ruff format, pyright, pytest, build) | |
| 120 | +| A skill's description, or a new skill | `npm run skills:eval` for the **whole** suite (spends model calls; not in CI). See `AGENTS.md` **Maintaining the skills** | |
| 121 | + |
| 122 | +Verify by exit code, not by grepping the output. Formatting failures are fixed |
| 123 | +with `npm run format` (TypeScript) or `uv run ruff format .` (Python). |
| 124 | + |
| 125 | +## 5. Client evidence |
| 126 | + |
| 127 | +A PR shows the change working, as the PR template's **How Has This Been |
| 128 | +Tested?** section asks. Here that means evidence from clients, not screenshots. |
| 129 | + |
| 130 | +**A change to server behavior** (a tool, resource, prompt, capability, |
| 131 | +transport or error it returns) records, for **both** the Inspector V2 and an |
| 132 | +LLM client, in **both** spec eras (a 2026-07-28 client and a 2025-11-25 client, |
| 133 | +per #4857): |
| 134 | + |
| 135 | +- what the client was asked to do (the Inspector action, or the prompt given to |
| 136 | + the LLM client), and |
| 137 | +- what it returned (the result, trimmed to what shows the change). |
| 138 | + |
| 139 | +A before/after pair is best when the change fixes a bug: the same request |
| 140 | +against `v2/main` and against the branch. |
| 141 | + |
| 142 | +**A change with no client-observable surface** (docs, skills, workflows, gate |
| 143 | +tooling, CI) carries a **targeted probe** instead: the one thing that proves |
| 144 | +it. For example, the guard made to fire on a planted defect and then pass, the |
| 145 | +workflow run that exercised the new job, the query that reads back the state a |
| 146 | +skill's recipe produced, or the `skills:eval` scores for a skill. |
| 147 | + |
| 148 | +Put the evidence in the PR body under **How Has This Been Tested?**. |
| 149 | + |
| 150 | +## 6. Open the PR |
| 151 | + |
| 152 | +Base **`v2/main`** (or the lower branch, when stacked). **Never `main`.** Label |
| 153 | +it `v2`. The body's **first line is `Closes #<N>`**. |
| 154 | + |
| 155 | +```sh |
| 156 | +gh pr create --repo modelcontextprotocol/servers \ |
| 157 | + --base v2/main --label v2 \ |
| 158 | + --title "<title>" --body "Closes #<N> |
| 159 | +
|
| 160 | +<what changed and why, then the template's sections, with the evidence>" |
| 161 | +``` |
| 162 | + |
| 163 | +⚠️ Closing keywords only link and auto-close for PRs that target the default |
| 164 | +branch (`main`). Against `v2/main`, `Closes #N` is only a cross-reference. |
| 165 | +Keep the line anyway, and **link the PR to the issue explicitly** right after |
| 166 | +opening it: |
| 167 | + |
| 168 | +```sh |
| 169 | +PR=<PR_NUMBER>; N=<ISSUE_NUMBER> |
| 170 | +PR_ID=$(gh pr view "$PR" --repo modelcontextprotocol/servers --json id --jq .id) |
| 171 | +ISSUE_ID=$(gh issue view "$N" --repo modelcontextprotocol/servers --json id --jq .id) |
| 172 | +gh api graphql -f query=' |
| 173 | + mutation($issue:ID!,$pr:ID!) { |
| 174 | + addCloseIssueReferences(input:{issueId:$issue, pullRequestIds:[$pr]}) { |
| 175 | + issue { number } |
| 176 | + } |
| 177 | + }' -f issue="$ISSUE_ID" -f pr="$PR_ID" |
| 178 | + |
| 179 | +# Read the link back: the issue number must be listed. |
| 180 | +gh pr view "$PR" --repo modelcontextprotocol/servers \ |
| 181 | + --json closingIssuesReferences --jq '[.closingIssuesReferences[].number]' |
| 182 | +``` |
| 183 | + |
| 184 | +The link does **not** make the issue close on merge into `v2/main`; that is |
| 185 | +still done by hand in step 9. |
| 186 | + |
| 187 | +Then move the card to **In Review** (`/board-ops`). The PR itself never goes on |
| 188 | +the board. |
| 189 | + |
| 190 | +## 7. Request a Copilot review |
| 191 | + |
| 192 | +Only the GraphQL `requestReviews` mutation with the Copilot **bot id** works. |
| 193 | +REST, `gh pr edit --add-reviewer`, `userIds` and `copilot-swe-agent` all fail or |
| 194 | +silently drop the request. |
| 195 | + |
| 196 | +```sh |
| 197 | +PR_ID=$(gh pr view <PR> --repo modelcontextprotocol/servers --json id --jq .id) |
| 198 | +gh api graphql -f query=' |
| 199 | + mutation($pr:ID!,$bot:[ID!]!) { |
| 200 | + requestReviews(input:{pullRequestId:$pr, botIds:$bot, union:true}) { |
| 201 | + pullRequest { id } |
| 202 | + } |
| 203 | + }' -f pr="$PR_ID" -f bot='BOT_kgDOCnlnWA' |
| 204 | +``` |
| 205 | + |
| 206 | +A round usually lands in about five minutes. Wait for it with **one backgrounded |
| 207 | +loop that exits when the round lands, or when its deadline passes**, and wait |
| 208 | +for its notification rather than re-fetching once per turn. A review is remote |
| 209 | +state the harness cannot observe, which is the exception in `AGENTS.md` |
| 210 | +**Waiting on long-running work**, and this loop is where that poll belongs. |
| 211 | + |
| 212 | +```sh |
| 213 | +PR=<PR> |
| 214 | +EXPECTED=1 # the review COUNT to reach; see below |
| 215 | +DEADLINE=$(( $(date +%s) + 20*60 )) |
| 216 | +while :; do |
| 217 | + # Capture first, so a gh failure stops the loop instead of being swallowed by |
| 218 | + # a pipeline. --slurp cannot be combined with --jq, hence the separate jq. |
| 219 | + raw=$(gh api --paginate --slurp \ |
| 220 | + repos/modelcontextprotocol/servers/pulls/$PR/reviews) || { |
| 221 | + echo "gh api failed ($?); not retrying blind" >&2; exit 1; } |
| 222 | + n=$(jq '[.[][] | select(.user.login | startswith("copilot-pull-request-reviewer"))] | length' <<<"$raw") || { |
| 223 | + echo "jq failed ($?) on an unexpected response shape" >&2; exit 1; } |
| 224 | + case $n in '' | *[!0-9]*) echo "not a count: '$n'" >&2; exit 1 ;; esac |
| 225 | + [ "$n" -ge "$EXPECTED" ] && { echo "round landed ($n reviews)"; break; } |
| 226 | + [ "$(date +%s)" -ge "$DEADLINE" ] && { echo "SILENT: no review by the deadline"; break; } |
| 227 | + sleep 30 |
| 228 | +done |
| 229 | +``` |
| 230 | + |
| 231 | +`EXPECTED` is the review **count** to reach, so it is `1` only on the first |
| 232 | +round; on round two the first round's review is still there, and an existence |
| 233 | +check would return at once. Match the login with `startswith`: it carries a |
| 234 | +`[bot]` suffix. `sleep 30` is the remote-API floor `AGENTS.md` sets. **Every |
| 235 | +step that can fail exits the loop rather than retrying**: piping the count into |
| 236 | +`awk` would make an auth error read as `0`, and an empty count from a `jq` |
| 237 | +failure would make the comparison fail forever, so the job sleeps and retries |
| 238 | +without end. A background task that can never succeed is worse than none, |
| 239 | +because it looks like progress. |
| 240 | + |
| 241 | +Once the body lands, give the inline comments about another 60 seconds: they |
| 242 | +arrive after it (step 8). |
| 243 | + |
| 244 | +## 8. Respond to the review |
| 245 | + |
| 246 | +Judge each finding against **the issue the PR closes**, as `AGENTS.md` |
| 247 | +**Responding to code reviews** says: fix defects in what the PR added; decline |
| 248 | +scope creep (pre-existing behavior, new capabilities, hardening the issue did |
| 249 | +not ask for) with a reason, and file an issue (`/issue-create`) for any that is |
| 250 | +worth doing on its own. Implementing a suggestion differently is fine. |
| 251 | + |
| 252 | +- **Reply to each review comment in its own thread**, saying what was done (with |
| 253 | + the commit) or why it was declined. That reply is the primary response, and it |
| 254 | + is not optional: each comment is a thread with its own resolve state, and a |
| 255 | + reply _in_ it is the only thing a reader of that thread sees. Replying does |
| 256 | + not resolve the thread; resolving is the reviewer's act. |
| 257 | + |
| 258 | + ```sh |
| 259 | + # The round's comments, by REVIEW id. The unpaginated /reviews listing hides |
| 260 | + # later rounds behind your own replies, and this endpoint returns 30 per page: |
| 261 | + # a round you only half fetch is a round you only half answer. |
| 262 | + gh api --paginate repos/modelcontextprotocol/servers/pulls/<PR>/reviews/<REVIEW_ID>/comments \ |
| 263 | + --jq '.[]|"\(.id) \(.path):\(.line)\n\(.body)\n"' |
| 264 | + |
| 265 | + # Reply into one thread, keyed by the comment id from above. |
| 266 | + gh api repos/modelcontextprotocol/servers/pulls/<PR>/comments/<COMMENT_ID>/replies \ |
| 267 | + -f body='Fixed in <sha>: …' |
| 268 | + ``` |
| 269 | + |
| 270 | +- ⚠️ **Then post a PR-level summary of the round, in addition, never instead.** |
| 271 | + Inline replies go hidden once the fix is pushed, because the threads become |
| 272 | + outdated, so the summary is what keeps the round readable afterwards. It does |
| 273 | + not replace the per-thread replies: a summary bullet cannot be connected back |
| 274 | + to the thread it answers. |
| 275 | + |
| 276 | + ```sh |
| 277 | + gh pr comment <PR> --repo modelcontextprotocol/servers --body "Copilot round <k>: …" |
| 278 | + ``` |
| 279 | + |
| 280 | +- ⚠️ **Read the "Suppressed comments" block in the review body.** Those findings |
| 281 | + have no comment id, so no thread to reply into. The PR-level summary is the |
| 282 | + only place to answer them. |
| 283 | +- ⚠️ **Inline comments lag the review body.** The body's "generated N comments" |
| 284 | + count lands first. Fetch by review id, and reconcile the count before |
| 285 | + answering. |
| 286 | + |
| 287 | +Push the fixes (signed off, step 3) before requesting the next round. |
| 288 | + |
| 289 | +## 9. Another round, or stop |
| 290 | + |
| 291 | +Request another round (step 7, with `EXPECTED` one higher) **only when you |
| 292 | +pushed a fix** in response to the last one. The loop stops at the **first** of: |
| 293 | + |
| 294 | +| Exit | When | Then | |
| 295 | +| --- | --- | --- | |
| 296 | +| **Clean round** | A review with no findings. No confirming round is needed | Stop | |
| 297 | +| **Out of scope only** | Every finding in the round was declined as outside the issue | Reply in each thread, stop. Nothing was pushed, so there is nothing new to review | |
| 298 | +| **Two silent rounds** | Two requests in a row end with no review: the poll's deadline passed, or Copilot's session ended without posting | Stop, and say so in the summary | |
| 299 | +| **Timeout** | The loop's overall budget is spent: about ten rounds, or the session is ending, while findings keep coming | Stop, and list what is still open in the summary so a human can pick it up | |
| 300 | + |
| 301 | +A round that posted nothing new is still reported in the PR-level summary, so |
| 302 | +the PR shows why the loop ended. |
| 303 | + |
| 304 | +## 10. Merge and close out |
| 305 | + |
| 306 | +Merging is a maintainer's decision. Do not merge on your own initiative. |
| 307 | + |
| 308 | +**On merge into `v2/main`, close the issue by hand and move its card to |
| 309 | +Done**, since auto-close does not fire there: |
| 310 | + |
| 311 | +```sh |
| 312 | +gh issue close <N> --repo modelcontextprotocol/servers --reason completed |
| 313 | +``` |
| 314 | + |
| 315 | +Then Status → **Done** with the move-a-card recipe in `/board-ops`. |
| 316 | + |
| 317 | +`Done` means the work **shipped**. If the PR is closed without merging and the |
| 318 | +issue will not be done, the issue shipped nothing: close it as not planned and |
| 319 | +**delete its card** (`/board-ops`) rather than moving it to Done. |
| 320 | + |
| 321 | +If PRs were stacked on this one, retarget each to `v2/main` (step 2). |
0 commit comments