generate-release-notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Notes Generator

Release Notes生成器

Generate release notes and changelogs by parsing conventional commit messages from git log history. Commits following the Conventional Commits specification (feat:, fix:, docs:, etc.) are categorized, grouped, and formatted into professional markdown output.

通过解析git log历史中的Conventional Commit消息来生成Release Notes和Changelog。遵循Conventional Commits规范（feat:、fix:、docs:等）的提交会被分类、分组，并格式化为专业的Markdown输出。

Workflow

工作流程

Step 1: Determine Output Type

步骤1：确定输出类型

Ask the user what they need:

Release Notes — a single release summary written to
```
RELEASE_NOTES.md
```
Changelog — append to an existing
```
CHANGELOG.md
```
(or create one)
Both — generate both files

询问用户的需求：

Release Notes — 单个版本的发布摘要，写入
```
RELEASE_NOTES.md
```
Changelog — 追加到现有的
```
CHANGELOG.md
```
（或创建新文件）
两者都要 — 同时生成两个文件

Step 2: Determine Commit Range

步骤2：确定提交范围

Identify which commits to include. Two approaches:

Since last tag (default): The parser script automatically detects the latest tag and uses

<tag>..HEAD

when no range is provided. To confirm the range with the user before generating, run

git describe --tags --abbrev=0

to display the latest tag.

Custom range: Accept a user-specified range like

v1.0.0..v2.0.0

v1.0.0..HEAD

and pass it as the first argument to the parser script.

If no tags exist, ask the user for a range or default to all commits (the script handles this automatically).

确定要包含的提交。有两种方式：

自上次标签起（默认）： 当未提供范围时，解析脚本会自动检测最新标签，并使用

<tag>..HEAD

作为范围。如需在生成前与用户确认范围，可运行

git describe --tags --abbrev=0

来显示最新标签。

自定义范围： 接受用户指定的范围，如

v1.0.0..v2.0.0

或

v1.0.0..HEAD

，并将其作为第一个参数传递给解析脚本。

如果不存在任何标签，询问用户提供范围或默认包含所有提交（脚本会自动处理这种情况）。

Step 3: Parse Commits

步骤3：解析提交

Run the parser script to extract structured commit data. The

${CLAUDE_PLUGIN_ROOT}

variable is set automatically by Claude Code when the plugin is installed:

bash

bash ${CLAUDE_PLUGIN_ROOT}/skills/generate-release-notes/scripts/parse-commits.sh [<range>]

The script outputs one block per commit with fields:

COMMIT

TYPE

SCOPE

BREAKING

DESCRIPTION

BODY

FOOTERS

运行解析脚本以提取结构化的提交数据。

${CLAUDE_PLUGIN_ROOT}

变量会在Claude Code安装插件时自动设置：

bash

bash ${CLAUDE_PLUGIN_ROOT}/skills/generate-release-notes/scripts/parse-commits.sh [<range>]

脚本会为每个提交输出一个块，包含以下字段：

COMMIT

、

TYPE

、

SCOPE

、

BREAKING

、

DESCRIPTION

、

BODY

、

FOOTERS

。

Step 4: Categorize and Format

步骤4：分类与格式化

Group parsed commits by type into sections using this mapping:

Type	Section Heading
feat	Features
fix	Bug Fixes
perf	Performance Improvements
refactor	Code Refactoring
docs	Documentation
style	Styles
test	Tests
build	Build System
ci	Continuous Integration
chore	Chores
revert	Reverts

Ordering: List sections in the order shown above. Within each section, list entries alphabetically by scope (ungrouped entries last).

Breaking changes: Collect all commits with

BREAKING:yes

into a dedicated "BREAKING CHANGES" section at the top, regardless of their type. These also appear in their normal type section.

Scope grouping: When multiple commits share a scope, group them under a bold scope label.

Commits with type "other": Collect into an "Other Changes" section at the bottom. These are commits that do not follow the conventional commit format.

按照以下映射，将解析后的提交按类型分组到不同章节：

类型	章节标题
feat	Features
fix	Bug Fixes
perf	Performance Improvements
refactor	Code Refactoring
docs	Documentation
style	Styles
test	Tests
build	Build System
ci	Continuous Integration
chore	Chores
revert	Reverts

排序规则： 按照上表所示顺序列出章节。在每个章节内，按scope字母顺序列出条目（无分组的条目放在最后）。

重大变更： 将所有标记为

BREAKING:yes

的提交收集到顶部的“BREAKING CHANGES”专属章节，无论其类型如何。这些提交也会出现在其所属的常规类型章节中。

Scope分组： 当多个提交共享同一个scope时，将它们分组在加粗的scope标签下。

类型为“other”的提交： 收集到底部的“Other Changes”章节中。这些是不符合Conventional Commit格式的提交。

Step 5: Determine Version

步骤5：确定版本号

If the user provides a version number, use it. Otherwise, suggest a version based on SemVer rules:

Any
```
BREAKING:yes
```
commit → suggest MAJOR bump
Any
```
feat
```
commit → suggest MINOR bump
Only
```
fix
```
,
```
docs
```
,
```
style
```
, etc. → suggest PATCH bump

Read the latest tag to determine the current version and calculate the next version. Present the suggestion and let the user confirm or override.

如果用户提供了版本号，则使用该版本号。否则，根据SemVer规则建议版本号：

存在任何
```
BREAKING:yes
```
提交 → 建议升级MAJOR版本
存在任何
```
feat
```
提交 → 建议升级MINOR版本
仅包含
```
fix
```
、
```
docs
```
、
```
style
```
等提交 → 建议升级PATCH版本

读取最新标签以确定当前版本，并计算下一个版本。呈现建议版本，让用户确认或覆盖。

Step 6: Write Output

步骤6：写入输出

Release Notes → Write to

RELEASE_NOTES.md

(overwrite previous content).

Changelog → Prepend new version entry to

CHANGELOG.md

. If the file does not exist, create it with a header. Preserve all existing entries below the new one.

Consult

references/formats.md

for the exact output templates.

Release Notes → 写入

RELEASE_NOTES.md

（覆盖原有内容）。

Changelog → 将新版本条目添加到

CHANGELOG.md

的开头。如果文件不存在，则创建文件并添加标题。保留新条目下方的所有现有内容。

有关确切的输出模板，请参考

references/formats.md

。

Step 7: Summary

步骤7：总结

After writing, display:

Version number used
Number of commits processed
Breakdown by category (e.g., "3 features, 2 bug fixes, 1 breaking change")
File(s) written

写入完成后，显示以下信息：

使用的版本号
处理的提交数量
按分类统计的结果（例如：“3个Features，2个Bug Fixes，1个重大变更”）
写入的文件

Handling Edge Cases

边缘情况处理

No conventional commits found: Warn the user that no parseable commits were found. Offer to list raw commit messages instead.

Mixed conventional and non-conventional: Process conventional commits normally, list non-conventional commits under "Other Changes."

Empty range: If the range produces no commits, inform the user and suggest checking the range.

Monorepo with scopes: When scopes map to packages/modules, offer to group by scope as top-level sections instead of by type.

未找到符合规范的提交： 警告用户未找到可解析的提交，提供列出原始提交消息的选项。

混合规范与非规范提交： 正常处理符合规范的提交，将非规范提交列在“Other Changes”下。

空范围： 如果范围未返回任何提交，告知用户并建议检查范围。

带有scope的单体仓库： 当scope对应包/模块时，提供按scope作为顶级章节分组的选项，而非按类型分组。

Additional Resources

额外资源

Reference Files

参考文件

For detailed output format templates and examples, consult:

references/formats.md
— Complete output templates for release notes and changelog, with examples of each section type

有关详细的输出格式模板和示例，请参考：

references/formats.md
— Release Notes和Changelog的完整输出模板，包含各章节类型的示例

Scripts

脚本

scripts/parse-commits.sh
— Parses git log into structured commit data. Accepts an optional range argument. Handles conventional commit parsing, scope extraction, breaking change detection, and footer parsing.

scripts/parse-commits.sh
— 将git log解析为结构化提交数据。接受可选的范围参数。处理Conventional Commit解析、scope提取、重大变更检测和页脚解析。