changelog-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog Generator Skill

Changelog 生成器 Skill

Generate changelogs from conventional commits for Java projects.

为 Java 项目从 Conventional Commits（约定式提交）生成变更日志。

When to Use

何时使用

Before a release
User says "generate changelog" / "update changelog" / "what changed since last release"
After completing a milestone

发布前
用户说“generate changelog” / “update changelog” / “what changed since last release”
完成一个里程碑后

Versioning Convention Detection

版本规范检测

Detect versioning style using this priority order:

按以下优先级检测版本管理风格：

1. Check CLAUDE.md (if exists)

1. 检查 CLAUDE.md（如果存在）

bash

grep -A5 "## Versioning" CLAUDE.md 2>/dev/null

Look for explicit convention:

markdown

undefined

bash

grep -A5 "## Versioning" CLAUDE.md 2>/dev/null

查找显式的规范：

markdown

undefined

Versioning

This project uses Semantic Versioning (x.y.z). Tag format:

release-x.y.z

undefined

This project uses Semantic Versioning (x.y.z). Tag format:

release-x.y.z

undefined

2. Fallback: Detect from git tags

2. 回退方案：从 Git tags 检测

bash

git tag --sort=-version:refname | head -10

Pattern detected	Versioning style
`v3.15.0` , `3.15.0`	SemVer (x.y.z)
`release-3.15.0`	SemVer with prefix
`v2.1` , `2.1`	Two-component (x.y)
`2026.01` , `26.1`	CalVer
No pattern	Ask user

bash

git tag --sort=-version:refname | head -10

检测到的模式	版本管理风格
`v3.15.0` , `3.15.0`	SemVer (x.y.z)
`release-3.15.0`	SemVer with prefix
`v2.1` , `2.1`	Two-component (x.y)
`2026.01` , `26.1`	CalVer
无模式	询问用户

3. Fallback: Detect from CHANGELOG.md

3. 回退方案：从 CHANGELOG.md 检测

bash

grep -E "^\#+ \[.*\]" CHANGELOG.md | head -5

Extract version format from existing entries.

bash

grep -E "^#+ \[.*\]" CHANGELOG.md | head -5

从现有条目中提取版本格式。

4. Last resort: Ask user

4. 最后手段：询问用户

No versioning convention detected. Which format does this project use?
- Semantic Versioning (x.y.z) - e.g., 3.15.0
- Two-component (x.y) - e.g., 2.1
- Calendar Versioning - e.g., 2026.01

No versioning convention detected. Which format does this project use?
- Semantic Versioning (x.y.z) - e.g., 3.15.0
- Two-component (x.y) - e.g., 2.1
- Calendar Versioning - e.g., 2026.01

Supported Versioning Styles

支持的版本管理风格

Style	Format	Tag examples	Version bump
SemVer	x.y.z	`v3.15.0` , `release-3.15.0`	major.minor.patch
Two-component	x.y	`v2.1` , `2.1`	major.minor
CalVer	YYYY.MM[.patch]	`2026.01` , `2026.01.1`	year.month[.patch]

风格	格式	Tag 示例	版本递增
SemVer	x.y.z	`v3.15.0` , `release-3.15.0`	major.minor.patch
Two-component	x.y	`v2.1` , `2.1`	major.minor
CalVer	YYYY.MM[.patch]	`2026.01` , `2026.01.1`	year.month[.patch]

Legacy Projects (CLAUDE.md without versioning section)

遗留项目（CLAUDE.md 不包含版本规范部分）

If CLAUDE.md exists but has no versioning info:

Don't assume - detect from tags/changelog

If detected, optionally suggest adding to CLAUDE.md:

Detected versioning: SemVer (x.y.z) with tag prefix 'release-'
Want me to add this to CLAUDE.md for future reference?

如果 CLAUDE.md 存在但没有版本信息：

不要臆测——从 tags/changelog 中检测

如果检测到，可以建议将其添加到 CLAUDE.md：

Detected versioning: SemVer (x.y.z) with tag prefix 'release-'
Want me to add this to CLAUDE.md for future reference?

Output Format

输出格式

Supports two formats - detect from existing CHANGELOG.md or ask user preference.

支持两种格式——从现有 CHANGELOG.md 检测，或询问用户偏好。

Format A: Keep a Changelog (h2 versions)

格式 A：Keep a Changelog（h2 版本标题）

markdown

undefined

markdown

undefined

Changelog

[Unreleased]

[1.2.0] - 2026-01-29

Added

[#123]: New feature for plugin dependencies

[#123]: New feature for plugin dependencies

Changed

[#456]: Improved performance of plugin loading

[#456]: Improved performance of plugin loading

Fixed

[#234]: Resolved NPE when directory missing

undefined

[#234]: Resolved NPE when directory missing

undefined

Format B: pf4j style (h3 versions)

格式 B：pf4j 风格（h3 版本标题）

markdown

undefined

markdown

undefined

Change Log

[Unreleased][unreleased]

[3.15.0] - 2026-01-29

Added

[#123]: New feature for plugin dependencies

[#123]: New feature for plugin dependencies

Changed

[#456]: Improved performance of plugin loading

[#456]: Improved performance of plugin loading

Fixed

[#234]: Resolved NPE when directory missing

undefined

[#234]: Resolved NPE when directory missing

undefined

Reference-Style Links (Recommended)

引用式链接（推荐）

Use reference-style links for cleaner, more readable entries:

markdown

undefined

使用引用式链接以生成更简洁、更易读的条目：

markdown

undefined

Fixed

[#648]: Restore missing
```
module-info.class
```
in multi-release JAR
[#625]: Fix exception handling inconsistency in
```
startPlugin()
```

[#648]: Restore missing
```
module-info.class
```
in multi-release JAR
[#625]: Fix exception handling inconsistency in
```
startPlugin()
```

Added

#629: Validate dependency state on plugin start
#633: Allow customization of
```
PluginClassLoader
```
parent delegation


**Benefits:**
- Cleaner to read (no long URLs inline)
- Links defined once, reusable
- Easier to write and maintain

#629: Validate dependency state on plugin start
#633: Allow customization of
```
PluginClassLoader
```
parent delegation


**优点：**
- 更简洁易读（无需内联长 URL）
- 链接定义一次，可重复使用
- 更易于编写和维护

Version Comparison Links

版本对比链接

Add comparison links at the bottom for easy diff viewing:

markdown

[unreleased]: https://github.com/user/repo/compare/release-3.15.0...HEAD
[3.15.0]: https://github.com/user/repo/compare/release-3.14.1...release-3.15.0
[3.14.1]: https://github.com/user/repo/compare/release-3.14.0...release-3.14.1

Pattern:

[version]: https://github.com/{owner}/{repo}/compare/{previous-tag}...{current-tag}

在文件底部添加对比链接，方便查看差异：

markdown

[unreleased]: https://github.com/user/repo/compare/release-3.15.0...HEAD
[3.15.0]: https://github.com/user/repo/compare/release-3.14.1...release-3.15.0
[3.14.1]: https://github.com/user/repo/compare/release-3.14.0...release-3.14.1

模式：

[version]: https://github.com/{owner}/{repo}/compare/{previous-tag}...{current-tag}

Section Order

章节顺序

Adapt to existing file, or use this default order:

Section	When to use
Fixed	Bug fixes
Changed	Changes to existing functionality
Added	New features
Deprecated	Soon-to-be removed features
Removed	Removed features
Security	Vulnerability fixes (CVEs)

Note: pf4j uses Fixed → Changed → Added → Removed. Keep a Changelog uses Added → Changed → Deprecated → Removed → Fixed → Security.

Rule: Follow existing file's order if present.

适配现有文件，或使用以下默认顺序：

章节	使用时机
Fixed	缺陷修复
Changed	对现有功能的更改
Added	新功能
Deprecated	即将移除的功能
Removed	已移除的功能
Security	漏洞修复（CVE）

注意：pf4j 使用 Fixed → Changed → Added → Removed。Keep a Changelog 使用 Added → Changed → Deprecated → Removed → Fixed → Security。

规则：如果文件已存在，遵循现有文件的顺序。

Mapping Conventional Commits to Changelog

将 Conventional Commits 映射到 Changelog

Commit Type	Changelog Section
feat	Added
fix	Fixed
perf	Changed
refactor	Changed
build(deps)	Changed or Security (if CVE)
BREAKING CHANGE	Changed (with bold note)
deprecate	Deprecated

提交类型	Changelog 章节
feat	Added
fix	Fixed
perf	Changed
refactor	Changed
build(deps)	Changed 或 Security（如果是 CVE）
BREAKING CHANGE	Changed（加粗说明）
deprecate	Deprecated

Workflow

工作流程

Check for existing CHANGELOG.md
bash
```
cat CHANGELOG.md | head -20
```
Detect format (h2 vs h3 versions, section order, link style).

Determine version range

bash

# Find last tag
git describe --tags --abbrev=0

# List recent tags
git tag --sort=-version:refname | head -5

Get commits since last release
bash
```
git log v3.14.1..HEAD --oneline
```
Extract issue/PR references Look for patterns:
```
#123
```
,
```
fixes #123
```
,
```
closes #123
```
,
```
(#123)
```
Generate changelog entry
- Group by section
- Use reference-style links
- Add version comparison link
Suggest version bump (based on detected versioning style)

SemVer (x.y.z):
- BREAKING CHANGE → Major (3.0.0 → 4.0.0)
- feat → Minor (3.14.0 → 3.15.0)
- fix only → Patch (3.14.0 → 3.14.1)
Two-component (x.y):
- BREAKING CHANGE → Major (2.0 → 3.0)
- feat/fix → Minor (2.1 → 2.2)
CalVer (YYYY.MM):
- New month → 2026.01 → 2026.02
- Same month, new release → 2026.01 → 2026.01.1

检查是否存在 CHANGELOG.md
bash
```
cat CHANGELOG.md | head -20
```
检测格式（h2 还是 h3 版本标题、章节顺序、链接风格）。

确定版本范围

bash

# Find last tag
git describe --tags --abbrev=0

# List recent tags
git tag --sort=-version:refname | head -5

获取自上次发布以来的提交
bash
```
git log v3.14.1..HEAD --oneline
```
提取 issue/PR 引用 查找模式：
```
#123
```
、
```
fixes #123
```
、
```
closes #123
```
、
```
(#123)
```
生成 changelog 条目
- 按章节分组
- 使用引用式链接
- 添加版本对比链接
建议版本递增（基于检测到的版本管理风格）

SemVer (x.y.z)：
- BREAKING CHANGE → Major (3.0.0 → 4.0.0)
- feat → Minor (3.14.0 → 3.15.0)
- 仅 fix → Patch (3.14.0 → 3.14.1)
Two-component (x.y)：
- BREAKING CHANGE → Major (2.0 → 3.0)
- feat/fix → Minor (2.1 → 2.2)
CalVer (YYYY.MM)：
- 跨月 → 2026.01 → 2026.02
- 同月新发布 → 2026.01 → 2026.01.1

Token Optimization

Token 优化

Use
```
git log --oneline
```
for initial scan
Only fetch full body if BREAKING CHANGE suspected
Reuse existing link definitions from file
Don't re-read entire changelog - just prepend new section

使用
```
git log --oneline
```
进行初始扫描
仅在怀疑有 BREAKING CHANGE 时才获取完整提交正文
复用文件中已有的链接定义
不要重新读取整个 changelog——只需在开头插入新章节

Example: Full Workflow

示例：完整工作流

Input: User says "generate changelog for next release"

Step 1: Check existing format

bash

head -30 CHANGELOG.md

→ Detects pf4j style (h3 versions, Fixed first)

Step 2: Find version range

bash

git describe --tags --abbrev=0

→

release-3.15.0

Step 3: Get commits

bash

git log release-3.15.0..HEAD --oneline

→ 5 commits found

Step 4: Generate entry

markdown

undefined

输入： 用户说“generate changelog for next release”

步骤 1： 检查现有格式

bash

head -30 CHANGELOG.md

→ 检测到 pf4j 风格（h3 版本标题，Fixed 在前）

步骤 2： 确定版本范围

bash

git describe --tags --abbrev=0

→

release-3.15.0

步骤 3： 获取提交

bash

git log release-3.15.0..HEAD --oneline

→ 找到 5 个提交

步骤 4： 生成条目

markdown

undefined

[Unreleased][unreleased]

Fixed

[#650]: Fix memory leak in extension factory

[#650]: Fix memory leak in extension factory

Changed

[#651]: Rename
```
LegacyExtension*
```
to
```
IndexedExtension*
```

[#651]: Rename
```
LegacyExtension*
```
to
```
IndexedExtension*
```

Added

[#652]: Add support for plugin priority ordering


**Step 5:** Generate link definitions
```markdown
[#652]: https://github.com/pf4j/pf4j/pull/652
[#651]: https://github.com/pf4j/pf4j/pull/651
[#650]: https://github.com/pf4j/pf4j/issues/650

Step 6: Update version comparison links

markdown

[unreleased]: https://github.com/pf4j/pf4j/compare/release-3.15.0...HEAD

Step 7: Suggest version

Suggested: 3.16.0 (minor - has new feature)

[#652]: Add support for plugin priority ordering


**步骤 5：** 生成链接定义
```markdown
[#652]: https://github.com/pf4j/pf4j/pull/652
[#651]: https://github.com/pf4j/pf4j/pull/651
[#650]: https://github.com/pf4j/pf4j/issues/650

步骤 6： 更新版本对比链接

markdown

[unreleased]: https://github.com/pf4j/pf4j/compare/release-3.15.0...HEAD

步骤 7： 建议版本

Suggested: 3.16.0 (minor - has new feature)

Handling Edge Cases

边界情况处理

No conventional commits

没有 conventional commits

List under "Changed" with original message:

markdown

undefined

在 “Changed” 下列出原始提交信息：

markdown

undefined

Changed

Updated plugin loading mechanism
Refactored test utilities

undefined

Updated plugin loading mechanism
Refactored test utilities

undefined

Security fix

安全修复

markdown

undefined

markdown

undefined

Security

[#618], [#623]: Fix path traversal vulnerabilities in ZIP extraction

undefined

[#618], [#623]: Fix path traversal vulnerabilities in ZIP extraction

undefined

Breaking change

破坏性变更

markdown

undefined

markdown

undefined

Changed

BREAKING: [#645] Renamed
```
LegacyExtension*
```
classes to
```
IndexedExtension*
```

undefined

BREAKING: [#645] Renamed
```
LegacyExtension*
```
classes to
```
IndexedExtension*
```

undefined

Multiple issues for same fix

同一修复关联多个 issue

markdown

- [#630], [#631]: Set `failedException` when plugin validation fails

markdown

- [#630], [#631]: Set `failedException` when plugin validation fails

Integration with Existing CHANGELOG.md

与现有 CHANGELOG.md 集成

Read existing file to detect:
- Heading level (## or ### for versions)
- Section order
- Link style (reference or inline)
- Existing link definitions
Insert new version after
```
[Unreleased]
```
section
Merge link definitions - add new ones, keep existing
Update
[unreleased]
comparison link to point to new version

读取现有文件 以检测：
- 标题级别（版本使用 ## 还是 ###）
- 章节顺序
- 链接风格（引用式或内联）
- 现有链接定义
插入新版本 到
```
[Unreleased]
```
章节之后
合并链接定义——添加新定义，保留现有定义
更新
[unreleased]
对比链接指向新版本

Quick Reference

快速参考

User says	Action
"generate changelog"	Full changelog since last tag
"changelog since v3.14"	From specific version
"what's unreleased"	Preview unreleased changes
"update changelog for 3.16"	Generate and insert for version
"add changelog entry for #123"	Single issue entry

用户说	操作
“generate changelog”	自上一个 tag 以来的完整 changelog
“changelog since v3.14”	从指定版本开始
“what's unreleased”	预览未发布的更改
“update changelog for 3.16”	为指定版本生成并插入
“add changelog entry for #123”	单个 issue 条目