release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release

版本发布

Cut a release, validate the changelog, and ensure git hooks are installed.

执行版本发布、验证变更日志，并确保Git Hooks已安装。

Usage

使用方法

/release 1.0.5

/release patch

(bumps patch from current version).

/release 1.0.5

或

/release patch

（从当前版本升级补丁版本）。

Process

执行流程

When the user triggers

/release <version>

Gather context — run
```
skills/release/scripts/release-context.sh <version>
```
. This silently installs git hooks and prints everything needed: version info, working directory status, commits since last release, files changed, current
```
[Unreleased]
```
content, and the previous release entry for style reference.
Commit outstanding work — if the context shows staged, modified, or untracked files that belong in this release, commit them first. Use the /commit skill or make well-formed commits directly.
Write the changelog — if
```
[Unreleased]
```
is empty, write it now using the commits and file changes from the context output. Follow the changelog standard below. Re-run the context script after committing if needed.
Cut the release — run
```
scripts/release.sh <version>
```
. This renames
```
[Unreleased]
```
→
```
[X.Y.Z] - date
```
, inserts a fresh
```
[Unreleased]
```
, bumps
```
package.json
```
, commits, and tags.
Show the final changelog — print the full
```
[Unreleased]
```
+ minor series rollup via
```
scripts/extract-changelog.sh <version>
```
. Ask the user to confirm before pushing.
Push — after explicit confirmation, run
```
git push origin main --tags
```
.
Watch CI — after the push, start a background dispatch to watch the publish workflow. Use
```
interactive_shell
```
in dispatch mode with:
```
gh run watch $(gh run list --workflow=publish.yml --limit=1 --json databaseId --jq '.[0].databaseId') --exit-status
```
The agent will be notified when CI completes and should report the result.

If any step fails, stop and explain. Never force-push or skip validation.

当用户触发

/release <version>

时：

收集上下文信息 — 运行
```
skills/release/scripts/release-context.sh <version>
```
。该脚本会静默安装Git Hooks，并打印所有必要信息：版本信息、工作目录状态、上一版本发布后的提交记录、变更文件、当前
```
[Unreleased]
```
部分的内容，以及上一个版本的条目作为格式参考。
提交未完成的工作 — 如果上下文信息显示存在属于本次发布的暂存、修改或未跟踪文件，请先提交这些内容。可以使用/commit技能，或直接创建格式规范的提交记录。
编写变更日志 — 如果
```
[Unreleased]
```
部分为空，请根据上下文输出中的提交记录和文件变更内容编写该部分。遵循下方的变更日志规范。提交后如有需要，可重新运行上下文脚本。
执行版本发布 — 运行
```
scripts/release.sh <version>
```
。该脚本会将
```
[Unreleased]
```
重命名为
```
[X.Y.Z] - 日期
```
，插入新的
```
[Unreleased]
```
部分，更新
```
package.json
```
版本号，提交变更并打标签。
展示最终变更日志 — 通过
```
scripts/extract-changelog.sh <version>
```
打印完整的
```
[Unreleased]
```
部分 + 次要版本系列汇总。在推送前请询问用户确认。
推送变更 — 获得用户明确确认后，运行
```
git push origin main --tags
```
。
监控CI流程 — 推送完成后，启动后台调度来监控发布工作流。使用调度模式下的
```
interactive_shell
```
执行：
```
gh run watch $(gh run list --workflow=publish.yml --limit=1 --json databaseId --jq '.[0].databaseId') --exit-status
```
当CI流程完成时，Agent会收到通知并应向用户报告结果。

如果任何步骤失败，请停止操作并说明原因。禁止强制推送或跳过验证步骤。

Changelog Standard

变更日志规范

The changelog lives in

CHANGELOG.md

and follows Keep a Changelog conventions.

变更日志存储在

CHANGELOG.md

中，遵循Keep a Changelog的约定。

Heading format

标题格式

```
## [Unreleased]
```
— accumulates entries between releases
```
## [X.Y.Z] - YYYY-MM-DD
```
— released versions

```
## [Unreleased]
```
— 累积两次发布之间的变更条目
```
## [X.Y.Z] - YYYY-MM-DD
```
— 已发布的版本

Structure of a release entry

版本条目的结构

Each version entry has two parts:

1. Highlights (optional, 1-4 sentences of prose)

Immediately after the version heading, before any

###

section. The elevator pitch — what would you tell someone in 30 seconds? Only for significant releases; skip for small patches.

markdown

undefined

每个版本条目包含两部分：

1. 亮点（可选，1-4句描述性文字）

紧跟在版本标题之后，位于所有

###

章节之前。相当于电梯游说——用30秒时间向用户介绍核心变化。仅适用于重要版本；小补丁版本可省略。

markdown

undefined

[1.1.0] - 2026-03-01

QMD now runs on both Node.js and Bun, with up to 2.7x faster reranking through parallel contexts. GPU auto-detection replaces the unreliable

gpu: "auto"

with explicit CUDA/Metal/Vulkan probing.


**2. Detailed changelog (`### Changes` and `### Fixes`)**

```markdown

QMD现在可在Node.js和Bun上运行，通过并行上下文实现最高2.7倍的重排序速度提升。GPU自动检测功能替代了不可靠的

gpu: "auto"

配置，改为显式探测CUDA/Metal/Vulkan。


**2. 详细变更日志（`### Changes`和`### Fixes`）**

```markdown

Changes

Runtime: support Node.js (>=22) alongside Bun. The
```
qmd
```
wrapper auto-detects a suitable install via PATH. #149 (thanks @igrigorik)
Performance: parallel embedding & reranking — up to 2.7x faster on multi-core machines.

运行时：支持Node.js (>=22)和Bun双环境。
```
qmd
```
包装器会通过PATH自动检测合适的安装环境。#149（感谢@igrigorik）
性能：并行嵌入与重排序——在多核机器上速度最高提升2.7倍。

Fixes

Prevent VRAM waste from duplicate context creation during concurrent
```
embedBatch
```
calls. #152 (thanks @jkrems)

undefined

避免在并发调用
```
embedBatch
```
时因重复创建上下文导致的显存浪费。#152（感谢@jkrems）

undefined

Writing guidelines

编写指南

Explain the why, not just the what. The changelog is for users.
Include numbers. "2.7x faster", "17x less memory".
Group by theme, not by file. "Performance" not "Changes to llm.ts".
Don't list every commit. Aggregate related changes.
Credit contributors: end bullets with
```
#NNN (thanks @username)
```
for external PRs. No need to credit the repo owner.

解释原因，而非仅描述内容。变更日志是面向用户的。
包含量化数据。比如“2.7倍更快”、“内存占用减少17倍”。
按主题分组，而非按文件分组。比如“性能优化”而非“llm.ts文件变更”。
不要列出每一个提交。将相关变更合并汇总。
感谢贡献者：外部PR的条目末尾需添加
```
#NNN (thanks @username)
```
。无需感谢仓库所有者。

What not to include

不应包含的内容

Internal refactors with no user-visible effect
Dependency bumps (unless fixing a user-facing bug)
CI/tooling changes (unless affecting the release artifact)
Test additions (unless validating a fix worth mentioning)

无用户可见影响的内部重构
依赖版本升级（除非修复了用户可见的问题）
CI/工具链变更（除非影响发布产物）
测试用例新增（除非用于验证值得提及的修复）

GitHub Release Notes

GitHub版本发布说明

Each GitHub release includes the full changelog for the minor series back to x.x.0. The

scripts/extract-changelog.sh

script handles this, and the publish workflow (

publish.yml

) calls it to populate the GitHub release.

每个GitHub版本包含从x.x.0开始的次要版本系列的完整变更日志。

scripts/extract-changelog.sh

脚本负责处理此内容，发布工作流（

publish.yml

）会调用该脚本来填充GitHub版本信息。

Git Hooks

The pre-push hook (

scripts/pre-push

) blocks

v*

tag pushes unless:

```
package.json
```
version matches the tag
```
CHANGELOG.md
```
has a
```
## [X.Y.Z] - date
```
entry for the version
CI passed on GitHub (warns in non-interactive shells, blocks in terminals)

Hooks are installed silently by the context script. They can also be installed manually via

skills/release/scripts/install-hooks.sh

or automatically via

bun install

(prepare script).

预推送钩子（

scripts/pre-push

）会阻止

v*

标签的推送，除非满足以下条件：

```
package.json
```
版本号与标签一致
```
CHANGELOG.md
```
中存在对应版本的
```
## [X.Y.Z] - 日期
```
条目
GitHub上的CI流程已通过（非交互式shell中发出警告，终端中直接阻止推送）

钩子会由上下文脚本静默安装。也可以通过

skills/release/scripts/install-hooks.sh

手动安装，或通过

bun install

自动安装（prepare脚本）。