Five findings, all valid. `runOutdated` accepted every exit status and returned `result.stdout ?? ""`. A failed `npm outdated` (exit 2 on a registry or config error) also prints nothing, so the empty string parsed to an empty package list — and across five installs a total outage produced output byte-identical to a clean sweep. It now throws on any status other than the documented 0/1. `main()` was untested, which is how that reached review: the helper-only suite passed while the silent-success path was live. It now takes its spawn function as a parameter and is driven by a fake, covering npm failure, create vs. edit, milestone handling, both no-op paths and the missing-repo guard. The no-op path returned before looking for the marker issue, so once every install caught up, a still-open tracking issue kept its obsolete package table indefinitely — contradicting the body's own promise to update in place. It now rewrites through `buildClearedBody()`. It deliberately does not close the issue: the sweep takes no board actions, and closing one whose card a maintainer may have moved would make the board assert work shipped that this script cannot verify shipped. The release step mandated `npm audit fix`, which AGENTS.md forbids. The reason is not `--force`: plain `audit fix` resolves an advisory with no upward escape in range by silently downgrading, as it did to esbuild across three installs in #2058, and `local:gate` has no version-regression check to catch it. The step is now `npm audit` report-only, with fixes applied deliberately via a direct bump or an `overrides` entry. An unmilestoned issue is swept into Incoming, not Todo — Todo asserts a maintainer signed off. Message corrected and pinned by a test. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RWMJENjs1mExXE5XPJTEei Signed-off-by: cliffhall <cliff@futurescale.com>
156 lines
8.2 KiB
Markdown
156 lines
8.2 KiB
Markdown
---
|
|
name: release
|
|
description: Cut an Inspector v2 release — run npm audit and bump the version on v2/main first, merge the milestone into main, tag origin/main with a bare x.y.z, and publish via the GitHub Release. Also covers the v1 line and what the publish jobs gate on.
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# Cutting a release
|
|
|
|
Background on what ships and why (the `files` allowlist, the bundling rules, the
|
|
container image) is in [`docs/publishing.md`](../../../docs/publishing.md). This
|
|
skill is the procedure.
|
|
|
|
A v2 release is cut from **`main`**, after the milestone's work has been merged
|
|
there from `v2/main` — not from `v2/main` itself. The v1 line releases
|
|
independently from `v1/main` to the `v1-latest` tag and never touches `main`.
|
|
|
|
Publishing is automated by two release-gated jobs in
|
|
`.github/workflows/main.yml` (`github.event_name == 'release'`), both
|
|
`needs: [build, coverage]` — so a release cannot publish with either the build
|
|
job or the coverage gate red:
|
|
|
|
- **`publish`** — runs `npm run pack:verify` as the pre-publish gate, asserts the
|
|
release tag matches the root `package.json` version, then `npm publish
|
|
--access public --provenance`.
|
|
- **`publish-github-container-registry`** — the GHCR image.
|
|
|
|
There is **one version number** (only the root `package.json` has one — the
|
|
clients carry none), so the flow is three steps.
|
|
|
|
## 1. `npm audit`, then bump, on `v2/main` — before the milestone merge
|
|
|
|
Both are part of the milestone's work, so both belong on the develop branch and
|
|
flow into `main` together, in the same PR — audit first, so the bump sits on top
|
|
of a tree you have just checked.
|
|
|
|
```sh
|
|
# Branch from the REMOTE ref, and read the version only once you are on it.
|
|
# A default clone has just `main` checked out, so a local `v2/main` may not
|
|
# exist and `package.json` here is `main`'s — the released version, not the one
|
|
# you are bumping from (Copilot).
|
|
git fetch origin v2/main
|
|
git checkout -b v2/chore/<ISSUE>-bump-<X-Y-Z> origin/v2/main
|
|
|
|
# Audit every install that has its own lockfile — root and each client.
|
|
# REPORT ONLY. Read the output; do not let npm mutate the tree (see below).
|
|
npm audit --audit-level=high
|
|
for c in web cli tui launcher; do (cd "clients/$c" && npm audit --audit-level=high); done
|
|
|
|
node -p "require('./package.json').version" # what is on v2/main now
|
|
npm version minor --no-git-tag-version # or major / patch; bump only, no tag
|
|
node -p "require('./package.json').version" # confirm, then PR → v2/main
|
|
```
|
|
|
|
Anything it reports is fixed **deliberately** — a direct bump, or an
|
|
`overrides` entry — and each fix is its own commit, gated by
|
|
`npm run local:gate` before the version bump goes on top.
|
|
|
|
⚠️ **Do not run `npm audit fix`, with or without `--force`.**
|
|
[Dependency placement](../../../AGENTS.md#dependency-placement) rules it out,
|
|
and the reason is not `--force`: plain `audit fix` resolves an advisory that has
|
|
no *upward* escape inside a declared range by silently **downgrading**. That is
|
|
not hypothetical here — `tsup@8.5.1` declares `esbuild: ^0.27.0` against an
|
|
advisory covering `0.27.3 - 0.28.0`, and `audit fix` walked three installs back
|
|
to `0.27.2` (~700 lines of lockfile churn for a low-severity dev-only advisory;
|
|
tried and reverted in #2058, written up in the `local-dev` skill). `local:gate`
|
|
does not detect a version regression, so nothing downstream would have caught
|
|
it. `--force` is worse again — it applies fixes *outside* the declared range,
|
|
trading a known vulnerability for an unvetted major.
|
|
|
|
So the release step is the **report**, and the judgment stays with a person.
|
|
Where `audit` names something with no in-range fix, pin it with `overrides`;
|
|
where it needs a major, that is its own issue and its own PR, not a release-day
|
|
edit. If something can't be resolved before the release ships, say so in the
|
|
release notes and leave it to the alert-driven pipeline (#2229) rather than
|
|
forcing it here.
|
|
|
|
This step is a **backstop, not a substitute** for #2229's alert-driven issues —
|
|
those are what surface a transitive vulnerability well before a release is cut,
|
|
tracked and fixed as their own PRs. This exists so a release is never gated on
|
|
remembering to check `npm audit` separately.
|
|
|
|
The branch name carries the version you are bumping **to**, so it is named after
|
|
that second reading. If you want it before branching:
|
|
`git show origin/v2/main:package.json | node -p "JSON.parse(require('fs').readFileSync(0)).version"`.
|
|
|
|
⚠️ **Never copy a version out of this file.** It would be a version that has
|
|
already shipped by the time you read it, and following it would cut a release
|
|
branch named for the wrong release (Copilot).
|
|
|
|
⚠️ **`--no-git-tag-version` is load-bearing.** A bare `npm version` also tags,
|
|
and the tag would land on a `v2/main` commit — but the release must be cut from
|
|
`main`, so the tag has to point at the merge commit there (step 3). Tagging here
|
|
creates a tag on a commit that is never released.
|
|
|
|
## 2. Merge `v2/main` → `main`
|
|
|
|
Through the usual milestone-merge branch. It now carries the bump, so the
|
|
release lands on `main` with the version already correct.
|
|
|
|
Between steps 1 and 2 the two branches **do** differ, and that is expected, not
|
|
drift: `v2/main` reads the version being built while `main` still reads the one
|
|
currently released. What this ordering removes is *post-release* drift — once the
|
|
milestone merge lands they agree again, and `v2/main` is never left **behind**
|
|
`main`. If you see `v2/main` ahead of `main`, a release is in flight; if you see
|
|
it behind, something went wrong.
|
|
|
|
## 3. Tag `origin/main` and draft the Release
|
|
|
|
Derive the tag from the version that just landed, rather than typing one — a
|
|
hard-coded tag is either already taken (so `git tag` aborts) or, worse, wrong:
|
|
|
|
```sh
|
|
git fetch origin main
|
|
VERSION=$(git show origin/main:package.json | node -p "JSON.parse(require('fs').readFileSync(0)).version")
|
|
echo "$VERSION" # sanity-check before tagging
|
|
git tag "$VERSION" origin/main && git push origin "$VERSION"
|
|
# then draft & publish a GitHub Release for that tag → triggers `publish`
|
|
```
|
|
|
|
⚠️ **Tag `origin/main`, not your local `HEAD`.** `git checkout main && git pull`
|
|
resolves through whatever merge-or-rebase strategy you have configured, so a
|
|
divergent local `main` can quietly produce or replay local commits. Tagging
|
|
`HEAD` there tags a commit that is not on `origin/main`, and `git push origin
|
|
<tag>` pushes only the tag — leaving a release whose commit was never published.
|
|
|
|
⚠️ **No `v` prefix.** This repo's release tags are bare `x.y.z` — which is why
|
|
the command above tags `$VERSION` and not `v$VERSION`. npm's own `tag-version-prefix` defaults to `v` and the repo
|
|
sets no `.npmrc`, so a bare `npm version` would have produced a mismatched tag;
|
|
tagging by hand is what keeps it right. (The workflow's assert step strips a
|
|
leading `v` before comparing, so a `v`-prefixed tag would still publish — it
|
|
would just be inconsistent with every previous release.)
|
|
|
|
The release's target commit selects which workflow runs, so this only publishes
|
|
when a release is cut from a commit carrying the v2 workflow.
|
|
|
|
## Why the bump goes on `v2/main` first (#2010)
|
|
|
|
It used to happen on the milestone-merge branch, which is cut from `main` — so
|
|
the bump existed only *downstream* of `v2/main` and nothing carried it back.
|
|
`v2/main` sat at `2.0.0` through both the 2.1.0 and 2.2.0 releases. That is not
|
|
cosmetic: a branch cut from a milestone-merge branch silently carries the bump
|
|
into an unrelated PR (this happened on #2009, where a container bugfix arrived
|
|
with a `2.0.0 → 2.2.0` diff), and anything reading the version in development
|
|
reported a version two releases old.
|
|
|
|
⚠️ **Never close a drift by merging `main` into `v2/main`.** `main` carries the
|
|
entire pre-v2 v1 history (~230 commits `v2/main` does not have), so a back-merge
|
|
grafts all of it into the develop branch's log permanently in order to deliver a
|
|
two-file change. Bumping first means there is nothing to back-merge.
|
|
|
|
## The v1 line
|
|
|
|
Flat: `feature branch → v1/main → npm v1-latest`, with no merge into `main` at
|
|
any point. The two lines publish independently under separate dist-tags, so a v1
|
|
fix does **not** need forward-porting to reach users on
|
|
`npx @modelcontextprotocol/inspector@v1-latest`.
|