changelog-composer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog Composer

Transforms raw git history and PR descriptions into polished, audience-appropriate changelogs. Parses conventional commits, classifies changes by impact category, filters internal-only modifications, and produces structured release notes with PR links — following Keep a Changelog conventions.

将原始Git历史记录和PR描述转换为符合受众需求的精美变更日志。解析约定式提交（conventional commits），按影响类别对变更进行分类，过滤仅内部的修改，并生成带有PR链接的结构化发布说明——遵循《Keep a Changelog》规范。

Reference Files

参考文件

File	Contents	Load When
`references/conventional-commits.md`	Commit type parsing, scope extraction, breaking change indicators	Repository uses conventional commits
`references/categorization-rules.md`	Change classification logic, audience filtering, severity ordering	Always
`references/audience-filter.md`	User-facing vs internal change detection, exclusion patterns	Always
`references/changelog-formats.md`	Keep a Changelog, GitHub Releases, announcement copy templates	Format selection needed

文件	内容	加载时机
`references/conventional-commits.md`	提交类型解析、范围提取、重大变更标识	仓库使用约定式提交时
`references/categorization-rules.md`	变更分类逻辑、受众过滤、优先级排序	始终加载
`references/audience-filter.md`	用户可见变更与内部变更的检测、排除规则	始终加载
`references/changelog-formats.md`	Keep a Changelog、GitHub Releases、公告文案模板	需要选择格式时

Prerequisites

前置条件

git — access to the repository history
gh (optional) — GitHub CLI for PR description extraction
A tagging strategy (semver tags) for identifying release boundaries

git —— 可访问仓库历史记录
gh（可选）—— GitHub CLI，用于提取PR描述
标签策略（语义化版本标签，semver tags），用于确定版本发布边界

Workflow

工作流程

Phase 1: Gather Raw Changes

阶段1：收集原始变更

Collect all changes between the previous release and the current state:

Identify boundaries — Find the last release tag:
```
git describe --tags --abbrev=0
```
. If no tags exist, use the initial commit or a user-specified starting point.

Extract commits —

git log <last-tag>..HEAD --oneline --no-merges

Extract PR titles —

gh pr list --state merged --base main --search "merged:>YYYY-MM-DD"

or parse merge commit messages.

Parse conventional commits — If the repository follows conventional commits (
```
feat:
```
,
```
fix:
```
,
```
docs:
```
, etc.), extract type, scope, and description. See
```
references/conventional-commits.md
```
.
Collect breaking change indicators — Look for
```
BREAKING CHANGE:
```
in commit bodies,
```
!
```
after type (
```
feat!:
```
), or explicit annotations in PR descriptions.

收集上一个版本发布到当前状态之间的所有变更：

确定边界 —— 查找最近的版本标签：
```
git describe --tags --abbrev=0
```
。如果没有标签，使用初始提交或用户指定的起始点。

提取提交记录 ——

git log <last-tag>..HEAD --oneline --no-merges

提取PR标题 ——

gh pr list --state merged --base main --search "merged:>YYYY-MM-DD"

或解析合并提交消息。

解析约定式提交 —— 如果仓库遵循约定式提交规范（
```
feat:
```
、
```
fix:
```
、
```
docs:
```
等），提取类型、范围和描述。详情见
```
references/conventional-commits.md
```
。
收集重大变更标识 —— 查找提交正文中的
```
BREAKING CHANGE:
```
、类型后的
```
!
```
（如
```
feat!:
```
），或PR描述中的显式标注。

Phase 2: Classify Changes

阶段2：分类变更

Categorize each change by its impact:

Category	Conventional Commit Type	Indicators
Breaking Changes	`feat!:` , `BREAKING CHANGE:`	API removal, signature change, behavior change
Features	`feat:`	New capability, new endpoint, new command
Fixes	`fix:`	Bug correction, error handling improvement
Performance	`perf:`	Speed improvement, memory reduction
Documentation	`docs:`	README, API docs, guides
Internal	`chore:` , `ci:` , `refactor:` , `test:` , `build:`	No user-facing impact

For repositories without conventional commits, classify by reading the commit message and changed files. Code changes to public API → Feature or Fix. Test-only changes → Internal.

按影响程度对每个变更进行分类：

类别	约定式提交类型	标识
重大变更	`feat!:` , `BREAKING CHANGE:`	API移除、参数签名变更、行为变更
新功能	`feat:`	新能力、新接口、新命令
问题修复	`fix:`	错误修正、错误处理优化
性能优化	`perf:`	速度提升、内存占用减少
文档更新	`docs:`	README、API文档、指南
内部变更	`chore:` , `ci:` , `refactor:` , `test:` , `build:`	无用户可见影响

对于未使用约定式提交的仓库，通过阅读提交消息和变更文件进行分类。公共API的代码变更→新功能或问题修复。仅测试文件的变更→内部变更。

Phase 3: Filter for Audience

阶段3：按受众过滤

Exclude internal changes by default:
- CI/CD configuration changes
- Test additions/modifications
- Dependency bumps (unless security-relevant)
- Code refactoring with no behavior change
- Build system changes
Include internal changes only when:
- They represent significant architecture shifts users should know about
- They affect development workflow (contributing guide changes)
- The changelog targets developers, not end-users
Highlight breaking changes prominently — always at the top, always with migration guidance.

默认排除内部变更：
- CI/CD配置变更
- 测试用例的添加/修改
- 依赖版本更新（除非涉及安全相关）
- 无行为变更的代码重构
- 构建系统变更
仅在以下情况包含内部变更：
- 代表用户应知晓的重大架构调整
- 影响开发工作流（如贡献指南变更）
- 变更日志面向开发者而非终端用户
突出显示重大变更 —— 始终放在最顶部，并附带迁移指导。

Phase 4: Compose Entries

阶段4：撰写条目

For each included change, write a human-readable description:

Lead with the impact — "Users can now..." or "Fixed issue where..."
Be specific — "Reduced memory usage by 40% for large file processing" not "Performance improvements"
Include migration guidance for breaking changes — what the user must change
Link to source — PR number, issue number, or commit hash

为每个入选的变更撰写易读的描述：

以影响为开头 —— 例如“用户现在可以...”或“修复了在...场景下的问题...”
具体明确 —— 例如“针对大文件处理将内存占用降低40%”而非“性能优化”
为重大变更添加迁移指导 —— 用户需要做出哪些修改
链接到源 —— PR编号、问题编号或提交哈希

Phase 5: Output

阶段5：输出

Assemble the changelog in the requested format, ordered by severity:

Breaking Changes (always first)
Features
Fixes
Performance
Documentation

按严重程度排序，将变更日志组装为指定格式：

重大变更（始终排在首位）
新功能
问题修复
性能优化
文档更新

Output Format

输出格式

undefined

undefined

[{version}] - {YYYY-MM-DD}

Breaking Changes

重大变更

function_name
parameter renamed —
```
old_param
```
is now
```
new_param
```
. Migration: find/replace
```
old_param=
```
with
```
new_param=
```
in all call sites. (#{pr})

function_name
参数重命名 ——
```
old_param
```
现已更名为
```
new_param
```
。迁移指导：在所有调用位置将
```
old_param=
```
替换为
```
new_param=
```
。(#{pr})

Features

新功能

{Feature name} — {What it enables and why it matters}. (#{pr})

{功能名称} —— {该功能的作用及重要性}。(#{pr})

Fixes

问题修复

Fixed {symptom} when {condition}. (#{pr})

修复了{症状}在{条件}下的问题。(#{pr})

Performance

性能优化

{Operation} is now {X}x faster / uses {X}% less memory. (#{pr})

{操作}现在速度提升{X}倍 / 内存占用减少{X}%。(#{pr})

Documentation

文档更新

Added {guide/reference} for {topic}. (#{pr})

undefined

添加了针对{主题}的{指南/参考文档}。(#{pr})

undefined

Configuring Scope

配置范围

Mode	Input	Output	When to Use
`release`	Tag-to-HEAD	Full changelog entry	Preparing a versioned release
`sprint`	Date range or commit range	Summary of changes	Sprint review, status update
`pr`	Single PR	One-line changelog entry	PR description template

模式	输入	输出	使用场景
`release`	标签到HEAD的范围	完整的变更日志条目	准备版本化发布时
`sprint`	日期范围或提交范围	变更摘要	迭代评审、状态更新时
`pr`	单个PR	单行变更日志条目	PR描述模板时

Calibration Rules

校准规则

User impact first. Every entry should answer "what does this mean for the user?" not "what did the developer do?"
Breaking changes are non-negotiable. Never omit or bury breaking changes. They go first, with migration guidance.
Specific over vague. "Fixed login timeout on slow connections" beats "Fixed bug." "Added CSV export for reports" beats "New feature."
Link everything. Every entry links to its source PR or issue. Users who want details can follow the link.
Exclude noise. Internal refactoring, dependency bumps, and CI changes do not belong in user-facing changelogs unless they have user-visible impact.

用户影响优先。每个条目都应回答“这对用户意味着什么？” 而非“开发者做了什么？”
重大变更不可妥协。绝不要省略或隐藏重大变更。它们必须排在首位，并附带迁移指导。
具体而非模糊。“修复了慢速网络下的登录超时问题”优于“修复了bug”。 “添加了报表的CSV导出功能”优于“新功能”。
所有内容都要链接。每个条目都要链接到对应的源PR或问题。需要详细信息的用户可以点击链接查看。
排除无关内容。内部重构、依赖版本更新和CI变更不属于面向用户的变更日志，除非它们有用户可见的影响。

Error Handling

错误处理

Problem	Resolution
No tags exist in repository	Ask for a starting commit or date. Default to the initial commit if the repository is small.
Repository doesn't use conventional commits	Classify by reading commit messages and changed files. Note reduced classification accuracy.
PR descriptions are empty or low-quality	Fall back to commit messages. Flag entries that may need manual review.
Ambiguous change classification	Default to "Features" for additions, "Fixes" for modifications. Mark uncertain entries for review.
Too many changes for a single release	Group by component/module. Consider whether the release should be split.
Merge commits obscure individual changes	Use `--no-merges` to skip merge commits. Parse individual commits within merged PRs.

问题	解决方法
仓库中无标签存在	请求用户提供起始提交 или 日期。如果仓库规模较小，默认使用初始提交。
仓库未使用约定式提交	通过阅读提交消息和变更文件进行分类。标注分类准确性降低。
PR描述为空或质量低下	回退到使用提交消息。标记可能需要人工审核的条目。
变更分类模糊	新增内容默认归类为“新功能”，修改内容默认归类为“问题修复”。标记不确定的条目以便审核。
单个版本的变更过多	按组件/模块分组。考虑是否应拆分版本发布。
合并提交掩盖了单个变更	使用 `--no-merges` 跳过合并提交。解析合并PR中的单个提交。

When NOT to Compose

不应使用此技能的场景

Push back if:

The user wants to auto-publish release notes without review — changelogs require human judgment
The repository has no meaningful commit history (single "initial commit" with everything)
The request is for marketing copy, not technical release notes — different skill
The changes are not yet merged — changelog is for shipped changes, not in-progress work

在以下情况时拒绝使用：

用户希望无需审核即可自动发布发布说明 —— 变更日志需要人工判断
仓库无有意义的提交历史（仅一个包含所有内容的“初始提交”）
请求的是营销文案而非技术发布说明 —— 属于不同技能范畴
变更尚未合并 —— 变更日志用于已发布的变更，而非进行中的工作