docs: add release runbook covering the next dist-tag two-step#355
Conversation
Promoting an RC to stable strands `next` on the superseded RC, so `@next` resolves older than `@latest`. `npm dist-tag add` would fix it, but publish.yml authenticates via OIDC trusted publishing and npm's OIDC covers only `npm publish` — dist-tag needs a traditional token this repo deliberately does not hold (npm/cli#8547). Documents the workaround (a second dispatch publishing a version forward onto `next`), its cost, and the GitHub "Latest" release realignment that run leaves behind. Also flags ci-cd-design.md as design intent: it names publish-npm.yml and an npm token setup, neither of which matches what ships. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
|
Warning Review limit reached
Next review available in: 42 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the CI/CD design documentation to note architectural drift and adds a detailed release runbook (releasing.md) covering workflow execution, release candidate promotion, and post-release steps. The review feedback is highly constructive, suggesting corrections to package name wildcards, clarification on how the preid parameter is supplied to the workflow, and the use of a version placeholder in the runbook's command examples to prevent copy-paste errors.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
|
||
| | Input | Notes | | ||
| | --- | --- | | ||
| | `package` | Must be `all` for a real publish. The workflow hard-fails otherwise: it rewrites every manifest, and lockfile regeneration needs every `@relayfile/mount-*` package already published at the new version so npm can resolve tarball integrity metadata. | |
There was a problem hiding this comment.
The wildcard @relayfile/mount-* does not match the directory name packages/local-mount (which typically maps to @relayfile/local-mount). If the package is named @relayfile/local-mount, update this reference to @relayfile/local-mount or @relayfile/*-mount to prevent confusion.
| | Input | Notes | | ||
| | --- | --- | | ||
| | `package` | Must be `all` for a real publish. The workflow hard-fails otherwise: it rewrites every manifest, and lockfile regeneration needs every `@relayfile/mount-*` package already published at the new version so npm can resolve tarball integrity metadata. | | ||
| | `version` | `patch` / `minor` / `major`, or `prerelease` with `preid=rc` for a release candidate. | |
There was a problem hiding this comment.
Clarify how preid=rc is passed to the workflow. If preid is a workflow input (e.g., -f preid=rc), it should be documented in the table and the example command. If it is automatically handled by the workflow when version=prerelease is selected, explicitly stating that would prevent confusion for operators.
| releases page matches the registry: | ||
|
|
||
| ```bash | ||
| gh release edit v0.10.27 --latest # the stable version, not the next-tag one |
There was a problem hiding this comment.
Use a placeholder like v<stable-version> instead of the hardcoded v0.10.27 in the gh release edit command. Since this is a runbook, operators are likely to copy-paste commands directly, and using a placeholder prevents accidental edits to the wrong release version.
| gh release edit v0.10.27 --latest # the stable version, not the next-tag one | |
| gh release edit v<stable-version> --latest # the stable version, not the next-tag one |
Relayfile Eval ReviewRun: Passed: 4 | Needs human: 0 | Reviewable: 0 | Missing output: 0 | Failed: 0 | Skipped: 0 Human Review CasesNo reviewable human-review cases captured Relayfile output. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1adde099eb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| releases page matches the registry: | ||
|
|
||
| ```bash | ||
| gh release edit v0.10.27 --latest # the stable version, not the next-tag one |
There was a problem hiding this comment.
On every promotion after this example, copying this runbook command will mark the old v0.10.27 release as Latest instead of the newly promoted stable version. This affects more than the releases page: scripts/install.sh:48-53 and scripts/install.sh:122-130 resolve /releases/latest and download binaries from that tag, so fresh installations can be downgraded. Use an explicit placeholder or a computed stable-version variable here.
Useful? React with 👍 / 👎.
| Downstream `^x.y.z` ranges resolve by semver across **all** published versions — | ||
| dist-tags do not gate them. A version published only to `next` will still | ||
| satisfy a caret range in a consumer's manifest on any lockfile refresh. Committed |
There was a problem hiding this comment.
Bare caret ranges do not resolve across all published versions: for example, 0.10.28-rc.0 does not satisfy ^0.10.27 because semver excludes prereleases unless the range explicitly opts into them. Only the stable 0.10.28 version produced by the workaround will enter that range, so this statement should distinguish stable versions published under next from ordinary RCs.
Useful? React with 👍 / 👎.
1 participant
Why
Promoting an RC to stable strands the
nextdist-tag on the superseded RC, so@nextresolves older than@latest. That happened on today's v0.10.27 release and took a while to diagnose — worth writing down rather than rediscovering.npm dist-tag addfixes this in one command, but it cannot run in this repo's CI:publish.ymluses OIDC trusted publishing, and npm's OIDC covers onlynpm publish/npm stage publish— every other command,dist-tagincluded, needs a traditional token. There's an open upstream issue for exactly this: npm/cli#8547. This repo holds no npm token by design, so the gap is structural, not an oversight.What
Adds
docs/releasing.md— an operational runbook:publish.yml(and whypackagemust beall)patchon a prerelease drops the prerelease (0.10.27-rc.0→0.10.27), it doesn't bump the patch digitnexttwo-step, whydist-tagisn't available, and the workaround's cost (publishes a version identical in content to the stable release)nextdispatch hijacks^x.y.zconsumer ranges resolve across all versions regardless of dist-tagAlso adds a drift note to
ci-cd-design.md, which describespublish-npm.ymland an "NPM Token Setup" — neither matches what ships today. It's design intent; the runbook is current state.Verification
Every claim was checked against
publish.ymlrather than written from memory:package=allenforcement →publish.yml:86-89grep -c "NPM_TOKEN\|NODE_AUTH_TOKEN"= 0publish.yml:604semver.inc('0.10.27-rc.0','patch')=0.10.27Docs only — no code, no changelog entry.
🤖 Generated with Claude Code