release-cut
Cut a new pi-agent-dashboard release: promote `## [Unreleased]` in CHANGELOG.md, bump every workspace package.json per SemVer, commit, tag `v<version>`, and push — triggering the Release workflow that publishes every non-private workspace, builds the Electron artifacts, and creates a GitHub Release. Use on "cut a release", "release vX.Y.Z", "publish a new version", "tag a release".
BlackBeltTechnology · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill release-cut技能说明
name: release-cut
description: 'Cut a new pi-agent-dashboard release: promote ## [Unreleased] in CHANGELOG.md, bump every workspace package.json per SemVer, commit, tag v<version>, and push — triggering the Release workflow that publishes every non-private workspace, builds the Electron artifacts, and creates a GitHub Release. Use on "cut a release", "release vX.Y.Z", "publish a new version", "tag a release".'
license: MIT
metadata:
author: pi-dashboard
version: "1.0"
Cut a pi-agent-dashboard Release
Canonical reference: docs/release-process.md.
This skill automates steps 1–5 of that doc. Production tags (vX.Y.Z)
publish the GitHub Release automatically — electron-updater's default
GitHub provider only resolves published, non-draft releases, so a draft
would silently block auto-update. Pre-release tags (vX.Y.Z-rc.N) stay
drafts so a maintainer can eyeball artifacts before flipping to published.
See change: fix-electron-auto-update-pipeline.
Pre-flight (MUST pass before touching anything)
Run these in order. If any fails, stop and report — do not continue.
-
Clean working tree
git status --porcelainMust be empty. If not, ask the user to commit or stash.
-
On the release branch
git rev-parse --abbrev-ref HEADMust be
develop(this repo has nomain). If elsewhere, ask user to confirm before continuing. -
Up to date with origin
git fetch origin && git status -sbBranch must NOT be "behind". If behind, ask user to pull first.
-
Tests pass
pnpm test -
Build succeeds
pnpm run build -
Dependency-shape gate (introduced by
enable-standalone-npm-installto prevent regressions of v0.5.3 publish-time bugs)node scripts/verify-release-deps.mjsAsserts critical runtime deps (
jiti, pinnednode-pty, etc.) are still declared in the publishable workspacepackage.jsonfiles. Failure means the next published tarball would be broken — STOP and fix the workspace before cutting.Known false-positive (substring gate).
verify-release-deps.mjschecks the declared range with a naiveString.includes(minVersion)— NOT semver math. So a legitimate pi bump ABOVE the floor (e.g. floor0.74.0, pin^0.80.10) fails the gate because"^0.80.10"does not contain the substring"0.74.0". When this fires and the pin is genuinely newer than the rule'sminVersion, the FIX is to bump that rule'sminVersion(+ its evidence note in the RULES array, and thescripts/AGENTS.mdrow) to the new floor — do NOT downgrade the pin. This recurs on every pi version bump. See change: fix-release-lockfile-drift (gate lives inscripts/verify-release-deps.mjs). -
Dispatch
ci-smoke.ymlagainstdevelop(recommended; catches installer regressions BEFORE the tag exists)The release pipeline (
publish.yml) gatespublishon arelease-gatethat runs the full 7-leg standalone-install-smoke matrix. If that gate fails onworkflow_dispatch,tag-and-pushis skipped — clean abort, no commit, no tag. But on agit push --tagscut, the tag already exists when the gate fires; failure leaves a dangling tag requiringrelease-revoke.Operators SHOULD run the smoke matrix first against
develop:gh workflow run ci-smoke.yml --ref develop gh run watch # or open the Actions UIAll 7 legs must be green before cutting. If any leg fails, fix the regression on
developfirst — do NOT cut a tag that you know will fail the gate. Skip this step only when the change since the last release is provably installer-irrelevant (no lockfile, bundle-server, native dep, or preload-fastify touch). See change: gate-publish-on-smoke-and-tests.
If any pre-flight step fails, stop and surface the exact error to the user.
Step 1 — Read current state
git describe --tags --abbrev=0 # last tag, e.g. v0.2.9
node -p "require('./package.json').version" # current pkg version
Confirm they match (e.g. tag v0.2.9 ↔ pkg 0.2.9). If they diverge,
surface the mismatch and ask the user how to proceed.
Step 2 — Curate ## [Unreleased]
- List commits since last tag:
git log <last-tag>..HEAD --oneline - Read
CHANGELOG.mdand extract the current## [Unreleased]section. - Cross-check: every
feat:/fix:commit should have a corresponding user-visible bullet under Added / Changed / Fixed. - If gaps exist, use AskUserQuestion to list missing items and confirm whether the user wants to add them now. If yes, draft bullets in end-user language (not commit-subject shorthand) and insert them.
- Never invent behaviour — only summarise what the commits actually did.
Far-behind escape hatch (long release cycle). If
[Unreleased]was not maintained per-change and the tag→HEAD span is huge (v0.6.0 was a 2-month, 906-commit release with only 24 of ~234 feat/fix changes documented), do NOT re-audit hundreds of commits by hand and do NOT dump raw commit subjects. Generate the deduped input set —git log <last-tag>..HEAD --onelinefiltered tofeat|fix|perf, minus the change-tags already in[Unreleased]— then delegate grouped drafting to a subagent (keeps quality high + your context focused). Merge the returned bullets under the existing headings programmatically (existing bullets first, new appended), scoped to the[Unreleased]section only, and cap the long tail with one rolled-up "Additional fixes" line. This is the exact path that worked for v0.6.0.
Step 3 — Decide next version (SemVer)
Propose per this decision tree, then use AskUserQuestion to confirm:
## [Unreleased] contains | Bump |
|---|---|
| Any breaking change / removal (call it out) | m |