Skip to content

release skill: add a final v1 step that walks the maintainer through npm deprecate #2954

Closed

Description

@cliffhall

Problem

npm deprecate is a point-in-time write, not a standing rule, so every v1 release lands on npm un-deprecated unless someone remembers to run it by hand. 1.0.2 shipped that way and was fixed after the fact (#2080). #2104 proposed automating it in v1/main's publish job, but that needs a long-lived npm token: OIDC trusted publishing covers npm publish only. Maintainers decided not to add and manage one, so #2104 was closed as not planned.

Deprecation therefore stays manual. Today the release skill's v1 flow (.claude/skills/release/SKILL.md, "The v1 line", steps v1-1 to v1-6) never mentions it, so the step relies on memory and has already been forgotten.

Proposal

Add a final step to the v1 flow that walks the maintainer through deprecating the version they just published. It goes after v1-5 (Verify), which confirms the publish actually landed. The step should cover:

  • Exact version, all four packages. Deprecate @modelcontextprotocol/{inspector,inspector-cli,inspector-client,inspector-server}@X.Y.Z.
  • ⚠️ Never a range. <2.0.0 also matches 2.0.0-rc.1/2/3 (a prerelease sorts below its release), so those v2 release candidates would get a v1 notice. If a range is ever genuinely needed, the safe spelling is <2.0.0-0.
  • The message, verbatim. It must match what is already on every v1 version. Read it back with npm view @modelcontextprotocol/inspector@<previous> deprecated rather than retyping it:
    v1 is deprecated. Upgrade to v2: npm i @modelcontextprotocol/inspector@latest. v1 gets security fixes only, published under the v1-latest tag.
  • ⚠️ An empty message lifts deprecation. npm deprecate pkg@ver "" un-deprecates, so a quoting slip silently reverses the step.
  • It is a human step. The publishing account requires 2FA for writes, so npm deprecate fails with EOTP unless given an OTP. An agent driving the release should stop and hand the maintainer the four exact commands (for example via ! npm deprecate … --otp=<code>), not attempt them itself. A TOTP code can expire between commands, so expect to supply fresh codes.
  • Verify. Check npm view @modelcontextprotocol/<pkg>@X.Y.Z deprecated --prefer-online for each of the four, and confirm 2.0.0-rc.* and the current latest stay un-deprecated.

Consider also listing the step in the v1 release issue's checklist, so the release isn't closed until it's done.

Acceptance criteria

  • The release skill's v1 flow ends with a deprecate step covering everything above
  • The step targets only the exact version just published and warns against the <2.0.0 range
  • The step states the message verbatim (or how to read it back) and warns that an empty message lifts deprecation
  • The step is framed as maintainer-run (2FA/OTP), with a verification command

Context

Activity

  1. added this to the v2.16.0 milestone on Nov 11, 2026
  2. added
    documentationImprovements or additions to documentation
    v2Issues and PRs for v2
    on Nov 11, 2026
  3. cliffhall commented on Nov 11, 2026

    @cliffhall
    MemberAuthor

    Triage: Priority Low (total 5)

    • Severity 2: minor friction with a workaround. A v1 release ships un-deprecated until someone runs npm deprecate by hand.
    • Urgency 2: wanted eventually. It only matters at the next v1 release, and nothing is blocked on it.
    • Bonuses: +1 milestone (v2.16.0)
  4. self-assigned this
    on Nov 12, 2026
  5. cliffhall commented on Nov 12, 2026

    @cliffhall
    MemberAuthor

    Shipped in #2968.

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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationv2Issues and PRs for v2

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions