go-live 8/9: post-swap docs, labels, boards, and integration hygiene #1821

Activity

1. cliffhall

   self-assigned this

   on Jul 27, 2026
2. cliffhall

   added

   v2Issues and PRs for v2Issues and PRs for v2

   on Jul 27, 2026
3. cliffhall

   changed the title [-]go-live 7/9: restrict PRs to collaborators; CONTRIBUTORS.md + SECURITY.md[/-] [+]go-live 8/9: post-swap docs, labels, boards, and integration hygiene[/+] on Jul 27, 2026
4. cliffhall

   added a parent issue on Jul 28, 2026

   • plan: v2 go-live runbook — deprecate v1 (1.0.1), branch v1/main, swap main to v2, publish 2.0.0, close v1 backlog, restrict external PRs #1804
5. cliffhall commented on Jul 28, 2026

   

   cliffhall

   on Jul 28, 2026

   MemberAuthor

   More actions

   Two items for this phase, found during phases 1–4

   1. Branch protection requires a reviewer the project does not have

   Both default-branch rulesets (2749948, 3187937, each targeting ~DEFAULT_BRANCH) require:

   required_approving_review_count: 1
   require_code_owner_review:       true
   

   and there is no CODEOWNERS file anywhere in the repo (CODEOWNERS, .github/CODEOWNERS, docs/CODEOWNERS all absent). The same shape was cloned onto v1/main in phase 1 (19858989).

   The consequence is that every merge goes through --admin bypass: #1827, #1828, #1829 on v1/main and #1830, #1831, #1832 on main all did. A required check that nothing can satisfy is worse than no check — it reads as protection while making bypass the routine path.

   ⚠️ Note the fix is not a CODEOWNERS file. GitHub forbids approving your own PR, so for a single maintainer required_approving_review_count: 1 is unsatisfiable regardless of who the code owner is — naming yourself in CODEOWNERS changes nothing, and dropping require_code_owner_review alone still leaves the count. The options are:

   1. A second reviewer with write access — the only path that satisfies the rule as written. Organizational, not technical.
   2. Align the rulesets with reality — drop the approval requirement on the default branch and rely on the required build check plus admin discipline. Honest, but weaker.
   3. Leave it and accept routine bypass — the current de facto state, which should at least be a decision rather than an accident.

   Deliberately not changed during phases 1–4: editing rulesets immediately before an irreversible npm publish adds risk without removing the need to bypass. Recording it here so it is resolved as a considered choice.

   2. Dependabot backlog — deferred, with reasoning

   72 open alerts as of 2026-07-28:

   Scope	Count	Severities
   runtime (ships to users)	38	14 high, 21 medium, 3 low
   development (never ships)	34	3 critical, 22 high, 5 medium, 4 low

   Why they do not block the 2.0.0 release (#1818): 2.0.0 ships the same dependency tree v2/main has carried all along. The swap changed nothing about it — main simply began reporting alerts it had never scanned before. Nothing regressed; visibility changed.

   On the three criticals: all are @vitest/browser, development scope. The published files allowlist is clients/*/build + clients/web/dist + scripts/install-clients.mjs, so dev dependencies are never in the tarball. They are not user-facing.

   One was investigated properly rather than triaged by severity — GHSA-frvp-7c67-39w9 (@hono/node-server, path traversal in serve-static), because the Inspector calls that exact function in its prod web server. Result: the advisory blocks .. escapes, so it only reaches files inside the static root by bypassing prefix-mounted middleware; here that root is the public SPA bundle and the only prefix middleware (/api/*) is a separate route, not a subdirectory. No auth bypass, no arbitrary read, Windows-only. Upgraded anyway in #1832 since it proved free.

   The plan:

   1. Ship 2.0.0 (go-live 5/9: publish 2.0.0 (rc under next first; rollback plan written first) #1818) on the current tree — no dependency changes in the release PR, so the publish diff stays minimal and reviewable.
   2. After the release, let Dependabot open its own PRs and land the transitive bumps in batches. Most of these are lockfile-only and resolve together.
   3. Re-audit the runtime-scope set specifically once the noise clears — those are the ones that reach users via npm install. Current runtime offenders: fast-uri (12), hono (15), @hono/node-server (fixed), qs, ip-address, yaml, body-parser, postcss.
   4. Treat dev-scope alerts as low priority by policy, and consider documenting that so future criticals in test tooling do not trigger a fire drill.

   The general lesson worth keeping: severity alone was a poor triage signal here. The three criticals were unshippable dev tooling; the one alert genuinely worth reading in full was a medium.
6. cliffhall

   modified the milestones: v2.2.0, v2.1.0 on Jul 28, 2026
7. cliffhall

   removed their assignment

   on Jul 29, 2026
8. cliffhall

   linked a pull request that will close this issuedocs: post-swap branch model, PR policy, milestone rule, and Copilot review instructions #1866on Jul 31, 2026
9. cliffhall commented on Jul 31, 2026

   

   cliffhall

   on Jul 31, 2026

   MemberAuthor

   More actions

   Task 1 — "Merges from v2/main into main enabled for milestone release workflow"

   Worked up against the real SHAs. Correction first: no graft/stitch commit is needed. The two branches already share history — I earlier concluded they didn't, but that was an artifact of a shallow local clone (git rev-parse --is-shallow-repository → true), which truncates history so git merge-base finds nothing. After git fetch --unshallow it resolves.

   Actual state

   Merge base	4d30d1cd — "docs: restore the missing docs/ targets and split the catalog-seeding wording (#1811) (#1812)"
   Established by	25106dcc — "Merge pull request #1830 from modelcontextprotocol/chore/v2-golive", which merged v2/main into main (the tree swap ec5d8e13 was part of that branch)
   main tip	fb1b0cb4 — "docs: restore SECURITY.md, lost in the v2 tree swap (#1843)"
   v2/main tip	5d91d4ac — "fix(core): mirror SEP-2243 x-mcp-header args to Mcp-Param-* on tools/call (#1847)"
   Divergence	main ahead by 223 (all v1 history + the 2.0.0 release commits), behind by 1

   The v1 history is reachable from main but not from v2/main, which is why the compare shows 223 — it is not 223 commits of pending work, and it does not affect the merge, because the 3-way merge compares trees against the base at 4d30d1cd.

   Verified by dry run

   Merging origin/v2/main into origin/main in a scratch worktree:

   • Succeeds as an ordinary merge — no --allow-unrelated-histories, no graft.
   • One conflict: README.md (the "Serving the modern protocol era" section — main carries a restructured version from go-live, v2/main extended the original prose). Every other file auto-merges: 13 files, +719/−33.
   • SECURITY.md survives the merge (added on main after the base, untouched on v2/main, so 3-way keeps it).

   The milestone merge sequence

   git fetch origin
   
   # 1. Merge the milestone's work into the release branch.
   git checkout -B main origin/main
   git merge --no-ff origin/v2/main -m "chore: merge v2/main for <version> milestone release"
   #    → resolve conflicts (today: README.md only), then `git add` + `git commit`
   
   # 2. Gate before it becomes the release.
   npm install && npm run ci
   
   # 3. Publish the branch, then cut the release from it.
   git push origin main
   npm version <major|minor|patch>   # on main — bumps root package.json + tags
   git push --follow-tags
   #    → draft & publish the GitHub Release for that tag; the `publish` job
   #      runs pack:verify and publishes the `latest` dist-tag
   
   # 4. Back-merge so the branches don't drift.
   git checkout -B v2/main origin/v2/main
   git merge --no-ff origin/main -m "chore: back-merge release commits from main into v2/main"
   git push origin v2/main

   Why step 4 matters

   v2/main is missing SECURITY.md today, and the version bump commits land on main only. Without the back-merge each milestone leaves v2/main a little further behind on release-only files, and the package.json version diverges — which is the one file most likely to conflict on every subsequent merge. The back-merge keeps the trees converged so each milestone merge stays as small as this one.

   Remaining checks before the first real run

   • Branch protection on main — confirm the ruleset permits a merge commit from a maintainer (or that the merge goes through a PR, if main requires one). This is the only thing that can block the sequence above; everything else is verified.
   • Decide whether step 1 goes through a PR (v2/main → main, reviewable, matches the "no direct pushes" posture) or a direct maintainer merge. A PR is the better default; note the PR body's Closes #N will not auto-close since main is the default branch — closing keywords work there, so it actually will. Worth confirming which issue such a release PR should reference.
   • Resolve the README.md conflict once by bringing main's restructured section onto v2/main ahead of the merge, so the first milestone merge is conflict-free.
10. cliffhall commented on Jul 31, 2026

    

    cliffhall

    on Jul 31, 2026

    MemberAuthor

    More actions

    Folded the task-1 analysis from my earlier comment into the issue description, along with the full ordered sequence, so the plan lives in one place rather than scattered across comments. That comment is now superseded — the description supersedes it wherever they differ (notably: it recommended a back-merge, which was built as #1868 and rejected).
11. cliffhall

    added sub-issues on Aug 1, 2026

    • SECURITY.md is missing from v2/main — the next milestone merge will drop it from main again #1864
    • Claude Code workflow (.github/workflows/claude.yml) and .mcp.json lost in the v2 tree swap — @claude no longer triggers #1850
    • Restore repo files dropped by the v2 tree swap (dependabot, issue template, .gitattributes, CoC) #1870
    • Post-swap docs: correct the branch model, PR policy, and stale AGENTS.md content #1873
    • Converge README.md on v2/main with main's restructured Test servers section #1874
    • Bring main's rc-series dependency bumps to v2/main (@hono/node-server 2.x, vite 8.1.5) #1875
    • Execute the first v2/main → main milestone merge and cut the release #1876
    • docs: reconcile the v1 policy wording and fix branch-pinned PR-template links #1813
    • Add .github/copilot-instructions.md so Copilot reviews against our actual conventions #1877
12. cliffhall

    self-assigned this

    on Aug 1, 2026
13. cliffhall

    removed a sub-issue on Aug 1, 2026

    • Execute the first v2/main → main milestone merge and cut the release #1876
14. cliffhall

    added sub-issues on Aug 1, 2026

    • Rename CONTRIBUTORS.md → CONTRIBUTING.md so GitHub surfaces the contributing policy #1883
    • Execute the first v2/main → main milestone merge and cut the release #1876
15. cliffhall

    added 2 commits that reference this issue on Aug 1, 2026

    docs: point the AGENTS.md policy link at CONTRIBUTING.md

    ...

    7fecc28

    docs: post-swap branch model, PR policy, milestone rule, and Copilot …

    ...

    3ac34e4
16. cliffhall

    removed a sub-issue on Aug 1, 2026

    • Execute the first v2/main → main milestone merge and cut the release #1876
17. cliffhall

    closed this as completedon Aug 1, 2026