changelog-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog Writer

变更日志生成工具

Generate changelogs, release notes, breaking change summaries, migration guides, and version bump recommendations from git history.

Scope: Changelog and release documentation only. NOT for git operations (git-workflow), documentation sites (docs-steward), or code review (review).

从Git历史记录生成变更日志、发布说明、重大变更摘要、迁移指南以及版本升级建议。

适用范围： 仅用于变更日志和发布文档。不适用于Git操作（git-workflow）、文档站点（docs-steward）或代码评审（review）。

Dispatch

调用方式

$ARGUMENTS	Mode
Empty / `generate`	Generate changelog from recent commits
`release <version>`	User-facing release notes for specific version
`breaking`	Breaking change detection and summary
`migration <from> <to>`	Migration guide between two versions
`bump`	Semantic version recommendation based on changes
Unrecognized input	Ask for clarification, show mode menu

参数	模式
空值 / `generate`	从近期提交记录生成变更日志
`release <version>`	特定版本的面向用户的发布说明
`breaking`	检测并汇总重大变更
`migration <from> <to>`	两个版本间的迁移指南
`bump`	根据变更内容推荐语义化版本升级
无法识别的输入	请求用户澄清，显示模式菜单

Canonical Vocabulary

标准术语表

Term	Definition
conventional commit	Commit following `type(scope): description` format
change type	Classification: feat, fix, refactor, perf, docs, chore, test, ci, build, style
breaking change	Backward-incompatible change, marked by `!` or `BREAKING CHANGE:` footer
scope	Component affected, in parentheses after type
changelog entry	Formatted line item in a changelog section
release notes	User-facing summary of changes for a version
migration guide	Step-by-step instructions to upgrade between versions
semver bump	major (breaking), minor (feat), patch (fix) recommendation
unreleased	Changes since the last tagged version

术语	定义
conventional commit	遵循 `type(scope): description` 格式的提交记录
change type	分类类型：feat（新功能）、fix（修复）、refactor（重构）、perf（性能优化）、docs（文档）、chore（杂项）、test（测试）、ci（持续集成）、build（构建）、style（格式）
breaking change	向后不兼容的变更，通过 `!` 或 `BREAKING CHANGE:` 脚注标记
scope	受影响的组件，位于类型后的括号中
changelog entry	变更日志章节中的格式化列表项
release notes	面向用户的版本变更摘要
migration guide	版本升级的分步指导说明
semver bump	版本升级建议：major（重大变更）、minor（新功能）、patch（修复）
unreleased	自上一个标记版本以来的变更

Mode 1: Generate Changelog

模式1：生成变更日志

Default mode. Produces a Keep a Changelog formatted document.

默认模式。生成符合《Keep a Changelog》格式的文档。

Step 1: Classify Commits

步骤1：分类提交记录

Run the commit classifier script:

uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]

Parse the JSON output. The script classifies each commit by conventional type and detects breaking changes.

运行提交分类脚本：

uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]

解析JSON输出。该脚本会按照规范提交类型对每个提交进行分类，并检测重大变更。

Step 2: Format Changelog

步骤2：格式化变更日志

Run the changelog formatter script:

uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]

The script converts classified commits to formatted markdown. Default format: Keep a Changelog.

运行变更日志格式化脚本：

uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]

该脚本会将分类后的提交记录转换为格式化的Markdown文档。默认格式为《Keep a Changelog》。

Step 3: Review and Refine

步骤3：审核与优化

Group entries by section (Added, Changed, Deprecated, Removed, Fixed, Security)
Rewrite terse commit messages into user-readable descriptions
Merge related commits into single entries where appropriate
Ensure breaking changes are prominently called out

Format reference: read references/changelog-conventions.md

按章节分组条目（新增、变更、弃用、移除、修复、安全）
将简洁的提交消息改写为用户易读的描述
酌情将相关提交合并为单个条目
确保重大变更被突出显示

格式参考：阅读 references/changelog-conventions.md

Mode 2: Release Notes

模式2：发布说明

release <version>

produces polished, user-facing release notes.

release <version>

用于生成经过打磨的、面向用户的发布说明。

Step 1: Identify Scope

步骤1：确定范围

Determine the range: last tag to HEAD (or between two tags if version already tagged).

bash

git log --oneline <previous-tag>..<version-or-HEAD>

确定提交范围：从上一个标记版本到HEAD（如果版本已标记，则为两个标记版本之间）。

bash

git log --oneline <previous-tag>..<version-or-HEAD>

Step 2: Classify and Group

步骤2：分类与分组

Run

commit-classifier.py

with the appropriate

--since

and

--until

flags. Group by user impact, not commit type:

Highlights — headline features (top 3-5)
Improvements — enhancements, performance gains
Bug Fixes — resolved issues
Breaking Changes — migration-required items (link to migration mode)
Contributors — credit contributors from git log

使用合适的

--since

和

--until

参数运行

commit-classifier.py

。按用户影响而非提交类型分组：

亮点 — headline级别的功能（前3-5项）
改进 — 功能增强、性能提升
Bug修复 — 已解决的问题
重大变更 — 需要迁移的内容（链接到迁移模式）
贡献者 — 从Git日志中感谢贡献者

Step 3: Write Release Notes

步骤3：撰写发布说明

Rewrite technical commit messages into user-facing language. Reference: read references/changelog-conventions.md, section "Release Note Style."

将技术化的提交消息改写为面向用户的语言。参考：阅读 references/changelog-conventions.md 中的“Release Note Style”章节。

Mode 3: Breaking Changes

模式3：重大变更检测

breaking

scans for backward-incompatible changes.

breaking

用于扫描向后不兼容的变更。

Step 1: Detect

步骤1：检测

Run the commit classifier with breaking-change focus:

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only [--since <tag>]

运行专注于重大变更的提交分类脚本：

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only [--since <tag>]

Step 2: Enrich

步骤2：补充信息

For each breaking change:

Identify the affected API/interface
Describe what changed and why
Provide the before/after code pattern
Assess blast radius (how many consumers affected)

Use patterns from

data/breaking-change-patterns.json

for language-specific detection.

针对每个重大变更：

确定受影响的API/接口
描述变更内容及原因
提供变更前后的代码示例
评估影响范围（受影响的消费者数量）

使用

data/breaking-change-patterns.json

中的模式进行特定语言的检测。

Step 3: Summarize

步骤3：汇总

Output a breaking changes report with severity ranking (high/medium/low) based on blast radius and migration effort.

输出带有严重程度排名（高/中/低）的重大变更报告，排名基于影响范围和迁移难度。

Mode 4: Migration Guide

模式4：迁移指南

migration <from> <to>

generates step-by-step upgrade instructions.

migration <from> <to>

生成分步升级指导。

Step 1: Collect Breaking Changes

步骤1：收集重大变更

Run commit classifier between the two versions:

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only --since <from> --until <to>

在两个版本之间运行提交分类脚本：

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only --since <from> --until <to>

Step 2: Generate Migration Steps

步骤2：生成迁移步骤

For each breaking change, produce:

What changed — old behavior vs new behavior
Action required — exact steps to migrate
Code example — before/after snippets
Verification — how to confirm the migration worked

Order steps by dependency (changes that must happen first go first).

针对每个重大变更，生成：

变更内容 — 旧行为 vs 新行为
需执行的操作 — 具体的迁移步骤
代码示例 — 变更前后的代码片段
验证方式 — 如何确认迁移成功

按依赖关系排序步骤（必须先执行的变更排在前面）。

Step 3: Compile Guide

步骤3：整理指南

Structure as a numbered checklist. Include a pre-migration checklist (backup, test suite green) and post-migration verification steps.

Reference: read references/changelog-conventions.md, section "Migration Guide Structure."

整理为编号清单。包含迁移前检查清单（备份、测试用例通过）和迁移后验证步骤。

参考：阅读 references/changelog-conventions.md 中的“Migration Guide Structure”章节。

Mode 5: Version Bump

模式5：版本升级建议

bump

recommends the next semantic version.

bump

推荐下一个语义化版本。

Step 1: Analyze

步骤1：分析

Run the commit classifier:

uv run python skills/changelog-writer/scripts/commit-classifier.py --since <last-tag>

Read the

suggested_bump

field from the JSON output.

运行提交分类脚本：

uv run python skills/changelog-writer/scripts/commit-classifier.py --since <last-tag>

读取JSON输出中的

suggested_bump

字段。

Step 2: Report

步骤2：报告

Present the recommendation with evidence:

Bump	Reason
major	Breaking changes detected: list them
minor	New features without breaking changes
patch	Bug fixes and non-functional changes only

Show the commit evidence supporting the recommendation. If commits are ambiguous (non-conventional format), flag uncertainty and ask for confirmation.

提供带有依据的建议：

升级类型	原因
major	检测到重大变更：列出具体内容
minor	新增功能且无重大变更
patch	仅包含Bug修复和非功能性变更

显示支持该建议的提交记录证据。如果提交记录不符合规范格式，标记不确定性并请求确认。

Reference Files

参考文件

Load ONE reference at a time.

File	Content	Read When
`references/changelog-conventions.md`	Keep a Changelog format, release note style, migration guide structure, semver decision tree	Formatting output in any mode
`references/commit-parsing.md`	Conventional commits parsing rules, breaking change detection heuristics	Understanding classifier output or edge cases

Data File	Content	Used By
`data/changelog-formats.json`	Format templates (Keep a Changelog, GitHub Releases, simple)	`changelog-formatter.py`
`data/breaking-change-patterns.json`	Language-specific breaking change detection patterns	`commit-classifier.py` , Mode 3 enrichment

Script	Purpose
`scripts/commit-classifier.py`	Parse git log, classify by conventional type, detect breaking changes
`scripts/changelog-formatter.py`	Convert classified commits JSON to formatted changelog markdown

每次仅加载一个参考文件。

文件	内容	读取时机
`references/changelog-conventions.md`	《Keep a Changelog》格式、发布说明风格、迁移指南结构、语义化版本决策树	任何模式下格式化输出时
`references/commit-parsing.md`	规范提交解析规则、重大变更检测启发式方法	理解分类器输出或处理边缘情况时

数据文件	内容	使用方
`data/changelog-formats.json`	格式模板（《Keep a Changelog》、GitHub Releases、simple）	`changelog-formatter.py`
`data/breaking-change-patterns.json`	特定语言的重大变更检测模式	`commit-classifier.py` 、模式3补充信息阶段

脚本	用途
`scripts/commit-classifier.py`	解析Git日志，按规范类型分类，检测重大变更
`scripts/changelog-formatter.py`	将分类后的提交记录JSON转换为格式化的变更日志Markdown

Critical Rules

关键规则

Never modify git history or run git operations beyond
```
git log
```
and
```
git tag
```
— this skill reads only
Always run
```
commit-classifier.py
```
before formatting — do not manually parse git log
Breaking changes must be prominently called out in every output format
Rewrite commit messages into user-readable language — raw commit text is not a changelog
Migration guides must include before/after code examples for every breaking change
Version bump recommendations must cite specific commits as evidence
When commits are non-conventional, classify by best-effort heuristics and flag uncertainty
Do not generate changelogs for uncommitted changes — only committed history
Always identify the previous tag as the baseline unless the user specifies otherwise
Credit contributors in release notes — extract from git log author fields

永远不要修改Git历史记录或执行
```
git log
```
和
```
git tag
```
之外的Git操作 — 本工具仅读取数据
格式化前必须先运行
```
commit-classifier.py
```
— 不要手动解析Git日志
重大变更必须在所有输出格式中突出显示
将提交消息改写为用户易读的语言 — 原始提交文本不能直接作为变更日志
迁移指南必须包含每个重大变更的前后代码示例
版本升级建议必须引用具体的提交记录作为依据
当提交记录不符合规范格式时，通过启发式方法进行分类并标记不确定性
不要为未提交的变更生成变更日志 — 仅处理已提交的历史记录
除非用户指定，否则始终以上一个标记版本为基线
在发布说明中感谢贡献者 — 从Git日志的作者字段提取信息