docs(runbook): add release-smoke.md (Codex final-pass item #3)#897
Merged
Conversation
Close the third drift item from Codex's final-pass review (after the v0.51.0–v0.55.0 sprint). Items #1 and #2 already landed: - #1 README Epic 1 status drift (PR #889) - #2 risk-map example (PR #896) - #3 release smoke runbook (this PR) Add docs/runbook/release-smoke.md as a sibling to docs/runbook/dev.md. It is not a release runbook (release-please handles tagging), but the smoke test that confirms a fresh tag installs cleanly for an adopter. Sections - When to run: post release-please merge, post dependabot prod-dep bump, pre announcement. - What it verifies: lint/tests/skills validate, river run dry-run, npm pack --dry-run, npm audit --omit=dev, GitHub Release presence. - Smoke sequence: single bash block, all commands must exit 0. - Release confirmation via gh: tagName / publishedAt / changelog body. - When the smoke fails: concrete recovery moves for the 5 common failure modes (lockfile drift, dist staleness, audit vuln, release 404, skill loader error), pointing at the existing docs and PRs that document each fix. - Out of scope: cross-platform install, npx river try, real LLM, Vercel. No code change. Refs: PRs #889, #896 (sibling Codex final-pass items), docs/development/npm-distribution-design.md, AGENT_LEARNINGS.md gh-api empty-commit entry. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No changes to review compared to main. |
Contributor
PlanGate Review
PlanGate review decision: pass
ポリシー: critical=fail / major=fail-if-required (warn) / minor=comment-only / info=skipped — spec: |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Comment on lines
+28
to
+29
| git fetch --tags origin | ||
| git checkout "v$(node -p 'require("./package.json").version')" |
Contributor
There was a problem hiding this comment.
The current sequence relies on the local package.json version to determine which tag to checkout. If the user has not yet pulled the latest changes from main after the release-please PR was merged, the local package.json will still contain the previous version, causing the wrong tag to be checked out. It is safer to ensure the local main branch is up to date first.
Suggested change
| git fetch --tags origin | |
| git checkout "v$(node -p 'require("./package.json").version')" | |
| git checkout main && git pull origin main | |
| git fetch --tags origin | |
| git checkout "v$(node -p 'require("./package.json").version')" |
| - **`npm ci` errors**: lockfile drift. Re-run `npm install` on `main` and open a PR to commit the new `package-lock.json`. The release tag itself is fine—the consumer error is the lockfile. | ||
| - **`Action dist freshness` mismatch (post-merge CI)**: someone forgot `npm run build:action` after editing `src/`. Open a small follow-up PR with the rebuilt `runners/github-action/dist/`. See `docs/development/dist-check-rebuild-guide.md`. | ||
| - **`npm audit --omit=dev` returns vulnerabilities**: open `npm audit fix --omit=dev` PR (see PR #888 for the pattern). | ||
| - **`gh release view` 404**: release-please workflow may have raced. Re-run `gh workflow run release-please.yml` against `main`, then re-check. See `feedback_release_please_workflow_race.md` memory if available. |
Contributor
There was a problem hiding this comment.
The reference to feedback_release_please_workflow_race.md appears to be a placeholder or refers to a file not present in the repository. The recovery pattern for the release-please race condition is documented in AGENT_LEARNINGS.md (lines 45-65). Updating this reference to point to the existing documentation would be more helpful for users troubleshooting this issue.
Both gemini comments are valid; apply. 1. Resolve TAG via the upstream GitHub Release instead of the local package.json. The previous form trusted that the operator had already pulled main after the release-please merge; if they had not, the local package.json could point at the previous version and the smoke would run against the wrong commit. Use `gh release view --json tagName --jq .tagName` so the upstream release is the source of truth. 2. The "feedback_release_please_workflow_race.md memory if available" pointer was misleading — that file is Claude's internal memory, not a repo doc. Replace with a concrete pointer to the AGENT_LEARNINGS.md 2026-05-24 entry that actually carries the gh-api empty-commit pattern in the repo. No content change beyond these two clarifications. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Close the third and last drift item from Codex's final-pass review (after the v0.51.0–v0.55.0 sprint). Items #1 and #2 already landed:
.river/risk-map.yamlexampledocs/runbook/release-smoke.mdis added as a sibling todocs/runbook/dev.md. It is not a release runbook (release-please handles tagging and the GitHub Release); it is the smoke test that confirms a freshv0.x.ytag installs and runs cleanly for an adopter.Sections
river run --dry-run,npm pack --dry-run,npm audit --omit=dev, GitHub Release presence.tagName/publishedAt/ changelog body.npx river try(C3), real LLM call (A2-2), Vercel preview.Test plan
🤖 Generated with Claude Code