release-changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Changelog Skill

稳定版本变更日志生成Skill

Generate the user-facing changelog for the stable Paperclip release.

Output:

```
releases/v{version}.md
```

Important rule:

even if there are canary releases such as
```
1.2.3-canary.0
```
, the changelog file stays
```
releases/v1.2.3.md
```

为Paperclip的稳定版本生成面向用户的变更日志。

输出：

```
releases/v{version}.md
```

重要规则：

即使存在如
```
1.2.3-canary.0
```
这类预览版本（canary release），变更日志文件仍需命名为
```
releases/v1.2.3.md
```

Step 0 — Idempotency Check

步骤0 — 幂等性检查

Before generating anything, check whether the file already exists:

bash

ls releases/v{version}.md 2>/dev/null

If it exists:

read it first
present it to the reviewer
ask whether to keep it, regenerate it, or update specific sections
never overwrite it silently

在生成任何内容之前，先检查目标文件是否已存在：

bash

ls releases/v{version}.md 2>/dev/null

若文件已存在：

先读取现有文件内容
将其展示给审核人员
询问是保留原文件、重新生成还是更新特定章节
绝对不能静默覆盖原文件

Step 1 — Determine the Stable Range

步骤1 — 确定稳定版本范围

Find the last stable tag:

bash

git tag --list 'v*' --sort=-version:refname | head -1
git log v{last}..HEAD --oneline --no-merges

The planned stable version comes from one of:

an explicit maintainer request
the chosen bump type applied to the last stable tag
the release plan already agreed in
```
doc/RELEASING.md
```

Do not derive the changelog version from a canary tag or prerelease suffix.

查找上一个稳定版本标签：

bash

git tag --list 'v*' --sort=-version:refname | head -1
git log v{last}..HEAD --oneline --no-merges

计划发布的稳定版本号来源包括：

维护人员的明确要求
基于上一个稳定版本标签选择的版本升级类型（major/minor/patch）
```
doc/RELEASING.md
```
中已确认的发布计划

请勿从预览版本（canary）标签或预发布版本后缀推导变更日志的版本号。

Step 2 — Gather the Raw Inputs

步骤2 — 收集原始输入数据

Collect release data from:

git commits since the last stable tag
```
.changeset/*.md
```
files
merged PRs via
```
gh
```
when available

Useful commands:

bash

git log v{last}..HEAD --oneline --no-merges
git log v{last}..HEAD --format="%H %s" --no-merges
ls .changeset/*.md | grep -v README.md
gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels

从以下渠道收集发布相关数据：

上一个稳定版本标签之后的git提交记录
```
.changeset/*.md
```
文件
当可以使用
```
gh
```
工具时，获取已合并的PR信息

实用命令：

bash

git log v{last}..HEAD --oneline --no-merges
git log v{last}..HEAD --format="%H %s" --no-merges
ls .changeset/*.md | grep -v README.md
gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels

Step 3 — Detect Breaking Changes

步骤3 — 检测破坏性变更

Look for:

destructive migrations
removed or changed API fields/endpoints
renamed or removed config keys
```
major
```
changesets
```
BREAKING:
```
or
```
BREAKING CHANGE:
```
commit signals

Key commands:

bash

git diff --name-only v{last}..HEAD -- packages/db/src/migrations/
git diff v{last}..HEAD -- packages/db/src/schema/
git diff v{last}..HEAD -- server/src/routes/ server/src/api/
git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true

If the requested bump is lower than the minimum required bump, flag that before the release proceeds.

需重点关注以下内容：

破坏性数据迁移
API字段/端点的移除或变更
配置项的重命名或移除
```
major
```
类型的变更集
提交信息中包含
```
BREAKING:
```
或
```
BREAKING CHANGE:
```
标识的内容

关键命令：

bash

git diff --name-only v{last}..HEAD -- packages/db/src/migrations/
git diff v{last}..HEAD -- packages/db/src/schema/
git diff v{last}..HEAD -- server/src/routes/ server/src/api/
git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true

若请求的版本升级类型低于实际需要的最低升级级别（如存在破坏性变更却只请求patch升级），需在发布前标记该问题。

Step 4 — Categorize for Users

步骤4 — 面向用户分类整理

Use these stable changelog sections:

```
Breaking Changes
```
```
Highlights
```
```
Improvements
```
```
Fixes
```
```
Upgrade Guide
```
when needed

Exclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.

Guidelines:

group related commits into one user-facing entry
write from the user perspective
keep highlights short and concrete
spell out upgrade actions for breaking changes

使用以下稳定版本变更日志章节：

```
Breaking Changes
```
（破坏性变更）
```
Highlights
```
（重点更新）
```
Improvements
```
（功能优化）
```
Fixes
```
（问题修复）
必要时添加
```
Upgrade Guide
```
（升级指南）

除非对用户有实质性影响，否则需排除纯内部重构、CI流程变更以及仅文档更新的内容。

编写指南：

将相关提交归为一条面向用户的条目
从用户视角出发撰写内容
重点更新部分需简洁具体
破坏性变更需明确说明升级操作步骤

Inline PR and contributor attribution

内嵌PR与贡献者署名

When a bullet item clearly maps to a merged pull request, add inline attribution at the end of the entry in this format:

- **Feature name** — Description. ([#123](https://github.com/paperclipai/paperclip/pull/123), @contributor1, @contributor2)

Rules:

Only add a PR link when you can confidently trace the bullet to a specific merged PR. Use merge commit messages (
```
Merge pull request #N from user/branch
```
) to map PRs.
List the contributor(s) who authored the PR. Use GitHub usernames, not real names or emails.
If multiple PRs contributed to a single bullet, list them all:
```
([#10](url), [#12](url), @user1, @user2)
```
.
If you cannot determine the PR number or contributor with confidence, omit the attribution parenthetical — do not guess.
Core maintainer commits that don't have an external PR can omit the parenthetical.

当某条变更条目明确对应一个已合并的PR时，需在条目末尾添加内嵌署名，格式如下：

- **功能名称** — 功能描述。([#123](https://github.com/paperclipai/paperclip/pull/123), @contributor1, @contributor2)

规则：

只有当你能确定条目与特定已合并PR直接关联时，才添加PR链接。可通过合并提交信息（
```
Merge pull request #N from user/branch
```
）来关联PR。
列出PR的作者贡献者，使用GitHub用户名，而非真实姓名或邮箱。
若多条PR共同贡献了一条变更条目，需全部列出：
```
([#10](url), [#12](url), @user1, @user2)
```
。
若无法确定PR编号或贡献者信息，请勿添加署名括号内容——切勿猜测。
核心维护者的提交若未关联外部PR，可省略署名括号。

Step 5 — Write the File

步骤5 — 编写变更日志文件

Template:

markdown

undefined

模板：

markdown

undefined

v{version}

Released: {YYYY-MM-DD}

发布日期: {YYYY-MM-DD}

Breaking Changes

Highlights

Improvements

Fixes

Upgrade Guide

Contributors

Thank you to everyone who contributed to this release!

@username1, @username2, @username3


Omit empty sections except `Highlights`, `Improvements`, and `Fixes`, which should usually exist.

The `Contributors` section should always be included. List every person who authored
commits in the release range, @-mentioning them by their **GitHub username** (not their
real name or email). To find GitHub usernames:

1. Extract usernames from merge commit messages: `git log v{last}..HEAD --oneline --merges` — the branch prefix (e.g. `from username/branch`) gives the GitHub username.
2. For noreply emails like `user@users.noreply.github.com`, the username is the part before `@`.
3. For contributors whose username is ambiguous, check `gh api users/{guess}` or the PR page.

**Never expose contributor email addresses.** Use `@username` only.

Exclude bot accounts (e.g. `lockfile-bot`, `dependabot`) from the list. List contributors
in alphabetical order by GitHub username (case-insensitive).

感谢所有为本版本做出贡献的开发者！

@username1, @username2, @username3


除`Highlights`、`Improvements`和`Fixes`（通常需保留）外，可省略空章节。

`Contributors`章节必须包含。列出发布版本范围内所有提交的作者，使用**GitHub用户名**（@username）标注，而非真实姓名或邮箱。查找GitHub用户名的方法：

1. 从合并提交信息中提取用户名：`git log v{last}..HEAD --oneline --merges` —— 分支前缀（如`from username/branch`）即为GitHub用户名。
2. 对于noreply邮箱（如`user@users.noreply.github.com`），用户名是`@`符号前的部分。
3. 若用户名不明确，可通过`gh api users/{guess}`或PR页面确认。

**绝对不能泄露贡献者的邮箱地址**，仅使用`@username`格式。

排除机器人账号（如`lockfile-bot`、`dependabot`）。按GitHub用户名的字母顺序（不区分大小写）排列贡献者。

Step 6 — Review Before Release

步骤6 — 发布前审核

Before handing it off:

confirm the heading is the stable version only
confirm there is no
```
-canary
```
language in the title or filename
confirm any breaking changes have an upgrade path
present the draft for human sign-off

This skill never publishes anything. It only prepares the stable changelog artifact.

在提交最终版本前：

确认标题仅包含稳定版本号
确认标题或文件名中无
```
-canary
```
相关字样
确认所有破坏性变更都提供了升级方案
将草稿提交给相关人员审核签字

本Skill仅负责生成稳定版本变更日志文件，不执行任何发布操作。