| name | npm-release |
| version | 1.1.0 |
| description | Use when ready to publish a new version of cc-devflow npm package to npm registry, including version sync, changelog finalization, git tag creation, and publish verification. |
| skill_class | maintenance |
| route_family | maintenance |
| reads | ["PLAYBOOK.md","CHANGELOG.md","references/git-commit-guidelines.md","../do-not-repeat-yourself/SKILL.md","references/checklist-contract.md"] |
NPM Release Workflow
Quick Start
- Read
PLAYBOOK.md, CHANGELOG.md, references/git-commit-guidelines.md, ../do-not-repeat-yourself/SKILL.md, and references/checklist-contract.md.
- Confirm the current worktree and branch are the user-approved release target.
- Run
git status --short, capture release_target_branch="$(git branch --show-current)", inspect current version and recent commits, then run npm whoami.
- Stop before real publish when git state, branch target, version conclusion, changelog, or npm auth is not proven.
npm-release 是内部维护 skill,不属于对外公开分发的五步 workflow。
Release Law
Release is atomic: package.json, package-lock.json, CHANGELOG.md, release
commit, annotated tag, pushed branch, pushed tag, and npm registry version must
describe the same version.
Release skills must never auto-switch branches. If the current worktree is not
already the user-confirmed release target, stop and ask for the correct release
worktree/branch or create a separate release worktree without changing the main
checkout.
Release commits follow references/git-commit-guidelines.md and run ../do-not-repeat-yourself/SKILL.md before staging.
Stop Conditions
- Current branch is not the user-confirmed release target.
- Uncommitted changes exist before release preparation.
- Unpushed commits exist and the user has not approved releasing from this branch state.
npm whoami fails for the publish registry.
- The release is pre-release/beta and no adaptation plan exists.
Release Flow
- Choose semver level:
| Type | Version Change | When |
|---|
patch | 2.4.3 -> 2.4.4 | Bug fixes, minor improvements |
minor | 2.4.4 -> 2.5.0 | Backward-compatible features |
major | 2.5.0 -> 3.0.0 | Breaking changes |
- Update
CHANGELOG.md, then update package.json and package-lock.json:
npm version <patch|minor|major> --no-git-tag-version
- Verify:
npm run verify:publish
npm pack --dry-run
- Commit:
git add CHANGELOG.md package.json package-lock.json
git commit -m "$(cat <<'EOF'
chore(release): bump version to X.Y.Z
问题:
- 公开包版本、CHANGELOG 和发布标签需要落到同一个可追溯节点。
变更:
- 更新 package version 和 CHANGELOG 到 X.Y.Z。
- 为 npm publish 准备 release commit。
原因:
- release commit 把版本标记和说明绑定,避免 tag 指向不可解释的历史。
验证:
- npm run verify:publish
- npm pack --dry-run
风险:
- 中:版本、tag、registry 三者必须保持一致;失败时按本 skill 的恢复流程处理。
EOF
)"
- Tag:
git tag -a vX.Y.Z -m "$(cat <<'EOF'
Release vX.Y.Z - <brief title>
Main changes:
- Change 1
- Change 2
Full changelog: https://github.com/Dimon94/cc-devflow/blob/main/CHANGELOG.md
EOF
)"
- Verify commit and tag:
git log --oneline -1
git show vX.Y.Z
- Push and publish:
git push origin "HEAD:${release_target_branch}"
git push origin vX.Y.Z
npm publish --dry-run
npm publish
npm view cc-devflow version
npx --yes cc-devflow@X.Y.Z --help
Failure Policy
git push failure: keep local commit/tag, capture the remote error, and retry the exact branch/tag push when network/auth recovers.
npm publish --dry-run failure: do not publish.
npm publish failure: capture registry output; do not delete local commit/tag to hide the failed release state.
- Published critical bug within npm's allowed unpublish window:
npm unpublish cc-devflow@X.Y.Z
git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z
git revert HEAD
After npm's unpublish window, publish a new patch instead.
Exit Criteria
package.json, package-lock.json, CHANGELOG.md, release commit, tag, and npm registry version match.
- Release commit and annotated tag point to the final changelog.
- Branch and tag push succeeded, or the remote blocker is captured.
npm publish succeeded, or the registry blocker is captured after dry-run prevented real publish.
- Post-publish smoke used
npm view and npx --yes cc-devflow@X.Y.Z --help.