release-bumper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Bumper

If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that case, do not invoke this skill again through a skill tool.

Release one package or several packages with version bumps, changelog entries, commits, and tags.

A non-dry-run invocation authorizes the repository-local version edits, changelogs, commits, and annotated tags defined by this workflow. Do not add a generic confirmation gate after the agent derives the release plan. Ask only when an unresolved package selection or dependency-range policy changes the release set or approach. GitHub release creation remains a separate external write governed below.

如果斜杠命令或美元符号调用已将这些指令加入对话，请直接遵循这些指令。在这种情况下，不要再次通过 skill 工具调用此 skill。

通过版本号升级、changelog 条目、commit 和 tag，发布一个或多个 package。

非 dry-run 调用即授权执行本工作流定义的仓库内版本修改、changelog、commit 和 annotated tag。Agent 推导出发布计划后，不要再添加通用确认环节。仅当 package 选择尚未解决，或 dependency-range 策略会改变发布集合或方案时，才向用户询问。GitHub release 创建仍是单独的外部写操作，并受下文规则约束。

Arguments

参数

```
packages
```
: optional package names or directories. Omit in a single-package repository.
```
version
```
: optional explicit semver. Valid only for one user-selected package.
```
--beta
```
: create or advance a
```
-beta.X
```
prerelease.
```
--dry-run
```
: preview without modifying files, committing, or tagging.

```
packages
```
：可选的 package 名称或目录。在单 package 仓库中可省略。
```
version
```
：可选的显式 semver。仅适用于用户选择的单个 package。
```
--beta
```
：创建或推进
```
-beta.X
```
prerelease。
```
--dry-run
```
：进行预览，不修改文件、不 commit、不 tag。

Helper Interface

Helper 接口

Resolve

<skill-dir>

from this

SKILL.md

. Keep helper stdout as JSON and diagnostics on stderr.

bun run "<skill-dir>/scripts/plan-release.ts" \
  [--cwd <repo>] [--beta] [--dry-run] [--version <semver>] \
  [--package <name-or-dir>]...

The read-only discovery output has

schemaVersion: 2

. It reports package identity, complete per-package

changedFiles

, workspace edges and declared ranges, previous-tag facts, selected targets, and worktree state.

changeHints

are filename-based, explicitly non-authoritative navigation hints. Never use them to decide release relevance or changelog inclusion.

After the agent decides every stable patch/minor/major version, write discovery JSON to a temporary file and run:

uv run "<skill-dir>/scripts/finalize-release-plan.py" \
  --discovery <discovery.json> \
  [--version <package>=<semver>]...

The finalizer performs beta and explicit-version transitions, stable prerelease promotion, npm-range satisfaction, simple dependency-range suggestions, and dependency ordering. It reports complex ranges, peer ranges, dependency cycles, and stable versions not supplied by the agent as unresolved decisions. When an unsatisfied edge adds a dependent, choose that package's release version and rerun with another

--version

assignment. The finalizer never chooses a regular release magnitude or dependency policy.

For every stable changelog written, validate its deterministic structure:

uv run "<skill-dir>/scripts/validate-changelog.py" \
  --file <CHANGELOG.md> --version <semver> --date <YYYY-MM-DD> [--tag <tag>]

This checks the expected release and date, heading/category order, allowed categories, list structure, and release-link tag. It does not judge importance, wording, or semantic category.

从该

SKILL.md

解析

<skill-dir>

。保持 helper 的 stdout 为 JSON，并将诊断信息写入 stderr。

bun run "<skill-dir>/scripts/plan-release.ts" \
  [--cwd <repo>] [--beta] [--dry-run] [--version <semver>] \
  [--package <name-or-dir>]...

只读 discovery 输出包含

schemaVersion: 2

。它会报告 package 标识、每个 package 的完整

changedFiles

、workspace 边和已声明的 ranges、previous-tag 的事实信息、选定的 targets 以及 worktree state。

changeHints

是基于文件名的、明确不具权威性的导航提示。绝不要使用它们决定 release 相关性或 changelog 收录范围。

在 Agent 确定所有稳定版本各自采用 patch、minor 或 major 后，将 discovery JSON 写入临时文件并运行：

uv run "<skill-dir>/scripts/finalize-release-plan.py" \
  --discovery <discovery.json> \
  [--version <package>=<semver>]...

finalizer 会执行 beta 和显式版本转换、将 prerelease 提升为稳定版、校验 npm-range 是否满足、提出简单的 dependency-range 建议并排列依赖顺序。它会将复杂 ranges、peer ranges、依赖循环，以及 Agent 未提供的稳定版本报告为未解决的决策。当某个未满足的 edge 需要加入 dependent 时，选择该 package 的 release version，并使用另一个

--version

assignment 重新运行。finalizer 绝不选择常规 release magnitude 或 dependency policy。

对于写入的每个稳定版 changelog，使用以下命令验证其固定结构：

uv run "<skill-dir>/scripts/validate-changelog.py" \
  --file <CHANGELOG.md> --version <semver> --date <YYYY-MM-DD> [--tag <tag>]

该命令会检查预期的 release 和 date、标题/分类顺序、允许的分类、列表结构以及 release-link tag。它不会判断重要性、措辞或语义分类。

Workflow

工作流

Run discovery with the user arguments mapped directly. Exit
```
2
```
means the target is not a releasable Git/package repository. Exit
```
64
```
means invalid input. Stop on either.
Require
```
workingTree.clean
```
. Do not absorb unrelated work.
Resolve unknown or ambiguous package selection. An explicit user version remains single-package only. If a target's
```
previousTags
```
version is below its manifest version, that version shipped untagged and the reported base is stale: create the missing annotated tag on its release commit (for example
```
docs: release <version>
```
) using the observed tag convention, include it in the push command, and rerun discovery. Ask only when no release commit is identifiable.
Inspect each target's complete
```
changedFiles
```
and the net diff from its previous tag. Decide whether the surviving changes warrant a release. Runtime environments, refactors, documentation, tests, and tooling can all be relevant in context. Filenames never decide this.
For every relevant stable target without an explicit version, choose patch, minor, or major from the consumer-facing change. For beta releases, let the finalizer compute the mechanical transition.
Run the finalizer. Review unsatisfied workspace edges. Accept its suggestion only for a simple dependency range when that policy fits. Choose peer and complex range policy explicitly. Add dependents and their agent-chosen release versions, then rerun until the package set and dependency order are resolved.
For a dry run, report the ordered package/version plan, range edits, changelog/tag/commit actions, and agent-decided skips. Stop before writes.
For a stable release, read
```
references/common-changelog.md
```
and write consumer-facing entries from the bounded net diff. The agent owns entry selection, wording, importance, and category. Beta releases do not update changelogs.
Update manifests and accepted dependency ranges. Validate every stable changelog with the helper.
Format once using the repository's narrowest established command.
Commit and tag dependencies before dependents. Use one commit and one annotated tag per package:
- single-package commit:
```
docs: release <version>
```
  .
- monorepo commit:
```
docs: release <package> <version>
```
  .
- single-package tag: follow observed
```
v<version>
```
  or bare-semver facts.
- monorepo tag: follow observed package tag facts, defaulting to
```
<package-dir>@<version>
```
  .
Do not push. After success, recommend an exact
```
git push origin <tag>...
```
command containing only the tags created by this execution. Do not use
```
--tags
```
.
Before the final report, inspect
```
.github/workflows/
```
for an active workflow that creates or publishes GitHub releases from pushed tags. A filename such as
```
release.yml
```
is a hint, not proof. Use
```
$cli-gh
```
to run
```
gh release list
```
read-only and check whether the repository has an established history of maintained GitHub releases. If it does, offer to create a GitHub release for each new tag, pending the user's approval, according to these rules:
- One to three tags and applicable release CI exists: do not offer manual release creation. In that case, the tag push should trigger CI.
- No applicable release CI exists: offer to create one release per new tag with
```
gh release create
```
  through
```
$cli-gh
```
  .
- More than three tags will be pushed together: offer to create one release per tag with
```
gh release create
```
  through
```
$cli-gh
```
  even when release CI exists, because GitHub does not create tag push events above that threshold. See GitHub's push-event limits.
Never create a GitHub release without the user's approval. If release history cannot be verified, report it as unknown and do not offer the write.
Before the final report, also inspect
```
.github/workflows/
```
for an active workflow that runs on pushed tags, sets
```
id-token: write
```
, and runs
```
npm stage publish
```
(staged) or
```
npm publish
```
(direct). A filename is a hint, not proof. If such a workflow exists:
- Report that pushing the recommended tags triggers npm publication.
- For staged publishing, report that each version stays unpublished until the maintainer approves it with 2FA. The maintainer can run
```
npm stage approve <stage-id>
```
  or use the Staged Packages tab on npmjs.com.
- Recommend push commands with at most three tags each, because GitHub creates no tag push events above that threshold. See the push-event limits link in step 13.
- Never run
```
npm publish
```
  ,
```
npm stage approve
```
  , or
```
npm stage reject
```
  .

将用户参数直接映射后运行 discovery。退出码
```
2
```
表示目标不是可发布的 Git/package 仓库；退出码
```
64
```
表示输入无效。遇到任一情况都应停止。
要求
```
workingTree.clean
```
。不要将无关工作纳入本次发布。
解析未知或有歧义的 package 选择。显式用户版本仍仅适用于单个 package。如果某个 target 的
```
previousTags
```
版本低于其 manifest 版本，说明该版本已经发布但未打 tag，且所报告的 base 已过期：在其 release commit 上按照观察到的 tag 约定创建缺失的 annotated tag（例如
```
docs: release <version>
```
），将其包含在 push 命令中，然后重新运行 discovery。只有在无法识别 release commit 时才询问。
检查每个 target 的完整
```
changedFiles
```
以及相对于其 previous tag 的净 diff。判断最终保留的变更是否值得发布。运行时环境、重构、文档、测试和工具链在上下文中都可能是相关的。绝不能仅凭文件名作出决定。
对于每个没有显式版本的相关稳定 target，根据面向消费者的变更选择 patch、minor 或 major。对于 beta release，让 finalizer 计算机械式版本转换。
运行 finalizer。审查未满足的 workspace edges。仅当相应策略适用时，才接受其针对简单 dependency range 提出的建议。明确选择 peer 和复杂 range 的策略。加入 dependents 及其由 Agent 选择的 release versions，然后重新运行，直至 package 集合和依赖顺序都得到解决。
对于 dry run，按顺序报告 package/version 计划、range edits、changelog/tag/commit 操作以及由 Agent 决定跳过的事项。在任何写入之前停止。
对于稳定版 release，读取
```
references/common-changelog.md
```
，根据限定范围内的净 diff 编写面向消费者的条目。条目选择、措辞、重要性和分类均由 Agent 负责。Beta release 不更新 changelog。
更新 manifests 和已接受的 dependency ranges。使用 helper 验证每个稳定版 changelog。
使用仓库中已确立且范围最窄的命令执行一次格式化。
按依赖顺序先为 dependencies 创建 commit 和 tag，再处理 dependents。每个 package 使用一个 commit 和一个 annotated tag：
- 单 package commit：
```
docs: release <version>
```
  。
- monorepo commit：
```
docs: release <package> <version>
```
  。
- 单 package tag：遵循观察到的
```
v<version>
```
  或 bare-semver 事实信息。
- monorepo tag：遵循观察到的 package tag 事实信息，默认使用
```
<package-dir>@<version>
```
  。
不要 push。成功后，推荐一条精确的
```
git push origin <tag>...
```
命令，其中只能包含本次执行创建的 tags。不要使用
```
--tags
```
。
在最终报告之前，检查
```
.github/workflows/
```
中是否存在处于启用状态且会根据 pushed tags 创建或发布 GitHub releases 的 workflow。诸如
```
release.yml
```
这样的文件名只是提示，并非证据。使用
```
$cli-gh
```
以只读方式运行
```
gh release list
```
，并检查仓库是否存在维护 GitHub releases 的既有历史。如果存在，则提议为每个新 tag 创建一个 GitHub release，但须获得用户批准，并遵循以下规则：
- 有 1 至 3 个 tags 且存在适用的 release CI：不要提议手动创建 release。在这种情况下，push tag 应触发 CI。
- 不存在适用的 release CI：提议通过
```
$cli-gh
```
  使用
```
gh release create
```
  为每个新 tag 创建一个 release。
- 将一起 push 超过 3 个 tags：即使存在 release CI，也提议通过
```
$cli-gh
```
  使用
```
gh release create
```
  为每个 tag 创建一个 release，因为 GitHub 在超过该阈值时不会创建 tag push events。参见 GitHub 的 push-event 限制。
绝不在未获用户批准的情况下创建 GitHub release。如果无法验证 release history，则将其报告为 unknown，且不要提议执行该写操作。
在最终报告之前，还要检查
```
.github/workflows/
```
中是否存在处于启用状态的 workflow：它会在 pushed tags 触发时运行，设置
```
id-token: write
```
，并运行
```
npm stage publish
```
（staged）或
```
npm publish
```
（direct）。文件名只是提示，并非证据。如果存在这样的 workflow：
- 报告推荐 push 这些 tags 会触发 npm 发布。
- 对于 staged publishing，报告每个版本在 maintainer 通过 2FA 批准前都保持未发布状态。Maintainer 可以运行
```
npm stage approve <stage-id>
```
  ，或使用 npmjs.com 上的 Staged Packages 标签页。
- 推荐每次最多包含三个 tags 的 push 命令，因为 GitHub 在超过该阈值时不会创建 tag push events。参见步骤 13 中的 push-event limits 链接。
绝不运行
```
npm publish
```
、
```
npm stage approve
```
或
```
npm stage reject
```
。

Safety and Completion

安全性与完成

Helper failures mean malformed input, violated invariants, or failed validation. An unresolved agent decision is data in the JSON, not a helper failure. Discovery and dry-run are read-only. Do not write changelogs before the final stable package set is known, and do not infer a tag convention when discovery reports observed facts.

Dry-run completion requires a discovery-backed, agent-reviewed action preview with zero writes. Release completion requires validated manifests and stable changelogs, formatting, one commit and annotated tag per package in dependency order, and a report of created commits/tags, agent-decided skips, the exact tag-push command or commands, any applicable GitHub release proposal, and any CI npm publication notice.

Use

### ⛔ Release stopped — working tree is not clean

### ⚠️ Release decision required

### 🔎 Release preview — no files, commits, or tags written

, or

### 🏁 Release complete

as applicable. Keep helper JSON, versions, hashes, tags, commands, and changelog text exact and undecorated.

Helper 失败意味着输入格式错误、不变量被违反或验证失败。尚未解决的 Agent 决策是 JSON 中的数据，而不是 helper 失败。Discovery 和 dry-run 均为只读操作。在最终稳定 package 集合确定之前，不要写入 changelog；如果 discovery 报告了观察到的事实，则不要推断 tag 约定。

完成 dry-run 需要提供有 discovery 依据、经 Agent 审核且零写入的操作预览。完成 release 需要验证 manifests 和稳定版 changelogs、执行格式化、按依赖顺序为每个 package 创建一个 commit 和 annotated tag，并报告已创建的 commits/tags、由 Agent 决定跳过的事项、精确的 tag-push 命令、任何适用的 GitHub release 提议，以及任何 CI npm 发布通知。

根据实际情况使用

### ⛔ Release stopped — working tree is not clean

、

### ⚠️ Release decision required

、

### 🔎 Release preview — no files, commits, or tags written

或

### 🏁 Release complete

。保持 helper JSON、版本号、哈希值、tags、命令和 changelog 文本原样准确，不加任何修饰。