changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog

变更日志

Generates human-readable changelogs from git commit history and manages the full release lifecycle. Commits automatically, pushes on request, tags and releases when told. Follows Keep a Changelog format and Conventional Commits conventions.

从git提交历史生成易读的变更日志，并管理完整的版本发布生命周期。可自动提交，按需推送，根据指令打标签和发布。遵循Keep a Changelog格式和Conventional Commits规范。

Capabilities

功能特性

Generate changelog from git commits (date range, tag range, or since last release)
Update existing changelog by adding new entries to the Unreleased section
Create new changelog with proper structure and initial content
Translate commits from developer language to user-friendly descriptions
Commit changelog updates automatically
Push changelog commits to remote on request
Tag and release with annotated tags on request

生成变更日志：从git提交记录生成（支持日期范围、标签范围或从上一次发布至今）
更新现有变更日志：在Unreleased章节添加新条目
创建新变更日志：生成结构规范的初始内容
提交信息转换：将开发者视角的提交信息转换为用户友好的描述
自动提交：自动提交变更日志的更新
按需推送：根据请求将变更日志提交推送到远程仓库
打标签与发布：根据指令创建带注释的标签并完成发布

Workflow Modes

工作流模式

When invoked, detect the mode from

$ARGUMENTS

and act accordingly:

/changelog [instructions]
    |
    +-- Mode: UPDATE (default)
    |   Update or create CHANGELOG.md, commit. No push.
    |
/changelog push
    |
    +-- Mode: PUSH
    |   Complete unreleased entries if new commits exist,
    |   commit if needed, push to remote.
    |
/changelog release [version]
    |
    +-- Mode: RELEASE
        Create versioned release entry, commit, tag, push.

Detection logic:

```
$ARGUMENTS
```
contains "release" (case-insensitive) → release mode
```
$ARGUMENTS
```
contains "push" (case-insensitive) → push mode
Everything else → update mode

Update mode handles: no arguments, date ranges, free-text instructions (e.g., "add this week's changes"). Always commits, never pushes.

Push mode handles:

/changelog push

. Completes the Unreleased section with any new commits not yet documented, commits if changes were made, then pushes.

Release mode handles:

/changelog release

(auto-detect version) or

/changelog release v2.0.0

(explicit version).

调用时，将从

$ARGUMENTS

中检测模式并执行相应操作：

/changelog [instructions]
    |
    +-- Mode: UPDATE (default)
    |   Update or create CHANGELOG.md, commit. No push.
    |
/changelog push
    |
    +-- Mode: PUSH
    |   Complete unreleased entries if new commits exist,
    |   commit if needed, push to remote.
    |
/changelog release [version]
    |
    +-- Mode: RELEASE
        Create versioned release entry, commit, tag, push.

检测逻辑：

```
$ARGUMENTS
```
包含"release"（不区分大小写）→ 发布模式
```
$ARGUMENTS
```
包含"push"（不区分大小写）→ 推送模式
其他情况 → 更新模式

更新模式处理：无参数、日期范围、自由文本指令（如"添加本周变更"）。始终执行提交，从不推送。

推送模式处理：

/changelog push

指令。若存在未记录的新提交，则补全Unreleased章节的内容，如有变更则提交，随后推送到远程仓库。

发布模式处理：

/changelog release

（自动检测版本）或

/changelog release v2.0.0

（指定版本）。

Pre-Flight Checks

前置检查

Run these checks before any git operations:

Clean working directory:
```
git status --porcelain
```
must return empty (CHANGELOG.md changes we are about to write are exempt). If dirty, abort and tell the user to commit or stash first.
Fetch latest remote state (push and release modes):
```
git fetch origin
```
Branch not behind remote (push and release modes): Compare local and remote with
```
git rev-list --count HEAD..origin/$(git branch --show-current)
```
. If behind, abort and tell the user to pull first.
No duplicate tag (release mode only): Check
```
git tag -l vX.Y.Z
```
. If the tag exists, abort and report the conflict.

在执行任何git操作前，需完成以下检查：

工作目录干净：
```
git status --porcelain
```
必须返回空（即将写入的CHANGELOG.md变更除外）。若目录不干净，需终止操作并告知用户先提交或暂存变更。
拉取最新远程状态（推送和发布模式）：
```
git fetch origin
```
本地分支未落后于远程（推送和发布模式）：通过
```
git rev-list --count HEAD..origin/$(git branch --show-current)
```
比较本地与远程分支。若本地落后，需终止操作并告知用户先拉取更新。
无重复标签（仅发布模式）：执行
```
git tag -l vX.Y.Z
```
检查。若标签已存在，需终止操作并报告冲突。

Creating a New Changelog

创建新变更日志

Verify no CHANGELOG.md exists at project root
Detect git remote URL for footer links:
```
git remote get-url origin
```
Get all tags:
```
git tag --sort=-v:refname
```
Analyse git history to gather commits
Categorize commits using Conventional Commits mapping (see references/changelog_format.md)
Generate CHANGELOG.md with:
- Header explaining the format
- Unreleased section with categorized changes
- Version sections for each existing tag (if any)
- Footer links to GitHub comparisons
Verify: Count entries match expected categorized commits
Write CHANGELOG.md to project root

验证项目根目录下不存在CHANGELOG.md
检测git远程仓库URL用于页脚链接：
```
git remote get-url origin
```
获取所有标签：
```
git tag --sort=-v:refname
```
分析git提交历史以收集提交记录
使用Conventional Commits映射对提交进行分类（详见references/changelog_format.md）
生成CHANGELOG.md，包含：
- 说明格式的标题
- 包含分类变更的Unreleased章节
- 每个现有标签对应的版本章节（若有）
- 指向GitHub对比页面的页脚链接
验证：条目数量与预期的分类提交数匹配
将CHANGELOG.md写入项目根目录

Updating an Existing Changelog

更新现有变更日志

Read existing CHANGELOG.md
Identify last documented version from existing content (look for
```
## [x.y.z]
```
headers)
Get corresponding tag:
```
git tag --sort=-v:refname | head -1
```
Gather commits since that point:
```
git log --oneline <last-tag>..HEAD
```
If no new commits: report "Changelog is up to date" and exit
Categorize new commits using Conventional Commits mapping
Add entries to Unreleased section (create section if missing)
Preserve all existing content exactly
Verify: New entry count matches new commit count (minus filtered)
Write updated CHANGELOG.md

读取现有CHANGELOG.md
从现有内容中识别最后记录的版本（查找
```
## [x.y.z]
```
标题）
获取对应的标签：
```
git tag --sort=-v:refname | head -1
```
收集从该版本到当前的提交记录：
```
git log --oneline <last-tag>..HEAD
```
若无新提交：报告"变更日志已为最新版本"并退出
使用Conventional Commits映射对新提交进行分类
将条目添加到Unreleased章节（若章节不存在则创建）
完全保留所有现有内容
验证：新条目数量与新提交数匹配（过滤后的提交除外）
写入更新后的CHANGELOG.md

Generating a Release Entry

生成发布条目

Triggered when

$ARGUMENTS

contains the word "release" (case-insensitive):

Determine the version:
- If the user provided a version (e.g.,
```
/changelog release v1.2.0
```
  ), use it directly
- Otherwise, auto-detect using Version Auto-Detection below
Gather commits since the last tag
Group by change type (Added, Changed, Fixed, etc.)
Filter noise (merge commits, CI/CD changes, refactors unless significant)
Translate technical commits to user-friendly descriptions
Create a versioned section with the version and today's date
Remove any existing Unreleased section and its footer link
Update footer comparison links

当

$ARGUMENTS

包含"release"（不区分大小写）时触发：

确定版本号：
- 若用户指定了版本（如
```
/changelog release v1.2.0
```
  ），直接使用该版本
- 否则，通过下方的版本自动检测功能获取版本
收集从上一个标签到当前的提交记录
按变更类型分组（新增、变更、修复等）
过滤无关内容（合并提交、CI/CD变更、无重大影响的重构）
将技术型提交信息转换为用户友好的描述
创建包含版本号和当前日期的版本章节
删除所有现有Unreleased章节及其页脚链接
更新页脚的对比链接

Post-Changelog Actions

变更日志后续操作

After writing CHANGELOG.md, run the appropriate git workflow.

写入CHANGELOG.md后，执行对应的git工作流。

Update Mode (default)

更新模式（默认）

```
git add CHANGELOG.md
```
```
git commit -m "Update changelog"
```
(use a descriptive message based on changes made)
Stop. Do not push. Report what was committed.

```
git add CHANGELOG.md
```
```
git commit -m "Update changelog"
```
（根据变更内容使用描述性的提交信息）
终止：不推送。报告已完成的提交操作。

Push Mode

推送模式

Check for new commits not yet in the Unreleased section. If found, add them first (follow the Updating an Existing Changelog steps above).
```
git add CHANGELOG.md
```
(if changes were made)
```
git commit -m "Update changelog"
```
(if changes were made)
```
git push
```
Verify:
```
git log --oneline -1
```
and confirm the push succeeded

检查Unreleased章节中是否有未记录的新提交。若有，先添加这些提交（遵循更新现有变更日志的步骤）。
```
git add CHANGELOG.md
```
（若有变更）
```
git commit -m "Update changelog"
```
（若有变更）
```
git push
```
验证：执行
```
git log --oneline -1
```
并确认推送成功

Release Mode

发布模式

```
git add CHANGELOG.md
```
```
git commit -m "Release vX.Y.Z"
```

git tag -a vX.Y.Z -m "Release vX.Y.Z - <one-line summary of changes>"

```
git push --follow-tags
```
Verify:
```
git ls-remote --tags origin | grep vX.Y.Z
```
and report the version, tag, and commit hash

```
git add CHANGELOG.md
```
```
git commit -m "Release vX.Y.Z"
```

git tag -a vX.Y.Z -m "Release vX.Y.Z - <one-line summary of changes>"

```
git push --follow-tags
```
验证：执行
```
git ls-remote --tags origin | grep vX.Y.Z
```
并报告版本号、标签和提交哈希

Git Analysis Commands

Git分析命令

bash

undefined

bash

undefined

All commits since last tag

git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD

Commits between tags

git log --oneline v1.0.0..v1.1.0

Commits in date range (adjust dates to match the requested period)

git log --oneline --since="2025-01-01" --until="2025-01-31"

Get current tags

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

undefined

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

undefined

Commit Categorization

提交分类

Map Conventional Commits prefixes to Keep a Changelog sections. See

references/changelog_format.md

for the full type-to-section mapping, writing style guidelines, and anti-patterns.

Quick reference:

Commit Prefix	Changelog Section
`feat:`	Added
`fix:`	Fixed
`refactor:` (user-visible)	Changed
`security:`	Security
`docs:` , `test:` , `ci:` , `chore:`	Filter out

Always include: features, user-facing bug fixes, breaking changes, security fixes. Always filter: merge commits, internal refactors, test changes, CI config, typos.

Translate technical commits to user-friendly language:

```
fix(auth): resolve JWT expiry edge case
```
-> "Fixed session timeout issues for long-running sessions"
```
feat(api): add /users endpoint
```
-> "Added user management API endpoints"

将Conventional Commits前缀映射到Keep a Changelog章节。完整的类型-章节映射、写作风格指南及反模式详见

references/changelog_format.md

。

快速参考：

提交前缀	变更日志章节
`feat:`	Added
`fix:`	Fixed
`refactor:` （用户可见）	Changed
`security:`	Security
`docs:` , `test:` , `ci:` , `chore:`	过滤

始终包含：新功能、面向用户的Bug修复、破坏性变更、安全修复。 始终过滤：合并提交、内部重构、测试变更、CI配置、拼写错误。

将技术型提交信息转换为用户友好的语言：

```
fix(auth): resolve JWT expiry edge case
```
→ "修复长会话的超时问题"
```
feat(api): add /users endpoint
```
→ "新增用户管理API端点"

Version Auto-Detection

版本自动检测

Automatically detects the next version from commits since the last tag. Used in release mode when the user does not provide an explicit version.

Step 1: Get the current version

bash

git tag --sort=-v:refname | head -1

If no tags exist, treat the current version as

0.0.0

Step 2: Scan commits since last tag for the highest bump signal

Check all commits since the last tag using

git log --pretty=format:"%s%n%b" <last-tag>..HEAD

. Apply the highest-priority rule that matches:

Priority	Signal	Bump
1	Breaking change -- BREAKING CHANGE in body/footer, or type! suffix (feat!, fix!)	Major
2	New feature -- feat or feat(scope) prefix	Minor
3	Bug fix or improvement -- fix, perf, or other included types	Patch

If all commits were filtered (docs, test, ci, chore only), output "No release needed" instead of a version.

Step 3: Output

Report the detected version:

Next version: X.Y.Z (bump -- reason)
Commits since vCURRENT: N total (N included, N filtered)

Use the auto-detected version to create the versioned release entry and the annotated tag. Do not ask the user for a version number.

See

references/changelog_format.md

for the full version detection rules and edge cases.

</instructions> <formatting>

从上一个标签后的提交记录中自动检测下一个版本号。当用户未指定版本时，在发布模式中使用该功能。

步骤1：获取当前版本

bash

git tag --sort=-v:refname | head -1

若无标签存在，将当前版本视为

0.0.0

。

步骤2：扫描上一个标签后的提交记录，识别最高优先级的版本升级信号

使用

git log --pretty=format:"%s%n%b" <last-tag>..HEAD

检查上一个标签后的所有提交。应用匹配的最高优先级规则：

优先级	信号	版本升级类型
1	破坏性变更 -- 提交正文/页脚包含BREAKING CHANGE，或类型后缀为!（如feat!, fix!）	主版本（Major）
2	新功能 -- 前缀为feat或feat(scope)	次版本（Minor）
3	Bug修复或改进 -- 前缀为fix、perf或其他包含的类型	修订版本（Patch）

若所有提交均被过滤（仅包含docs、test、ci、chore类型），则输出"无需发布新版本"而非版本号。

步骤3：输出

报告检测到的版本：

Next version: X.Y.Z (bump -- reason)
Commits since vCURRENT: N total (N included, N filtered)

使用自动检测到的版本创建版本发布条目和带注释的标签。无需向用户询问版本号。

完整的版本检测规则及边缘情况详见

references/changelog_format.md

。

</instructions> <formatting>

Output Format

输出格式

Generate changelog following this structure:

markdown

undefined

生成的变更日志需遵循以下结构：

markdown

undefined

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

Added

New feature description

New feature description

Changed

Modified behavior description

Modified behavior description

Fixed

Bug fix description

Bug fix description

[1.0.0] - YYYY-MM-DD

Added

Initial release features


</formatting>

Initial release features


</formatting>

Examples

示例

<example> **User request**: `/changelog` (no arguments, no existing CHANGELOG.md) **Mode**: Update **Action**: No CHANGELOG.md found. Create from full git history. Commit. **Steps**: 1. Generate CHANGELOG.md from all commits 2. `git add CHANGELOG.md` 3. `git commit -m "Add changelog from git history"` **Output**: Created CHANGELOG.md and committed. Run `/changelog push` when ready to push. </example> <example> **User request**: `/changelog` (existing CHANGELOG.md, new commits since last tag) **Mode**: Update **Action**: Add new entries to Unreleased section. Commit. **Steps**: 1. Update CHANGELOG.md with new Unreleased entries 2. `git add CHANGELOG.md` 3. `git commit -m "Update changelog with recent changes"` **Output**: Updated Unreleased section and committed. </example> <example> **User request**: `/changelog push` **Mode**: Push **Action**: Check for new commits not yet in Unreleased. Complete the section if needed. Commit and push. **Steps**: 1. Find 3 commits not yet documented, add to Unreleased section 2. `git add CHANGELOG.md` 3. `git commit -m "Update changelog with recent changes"` 4. `git push` **Output**: Added 3 entries to Unreleased, committed, and pushed to remote. </example> <example> **User request**: `/changelog release` or `/changelog release v2.0.0` **Mode**: Release **Action**: Detect version automatically from commit types, or use the explicit version provided. Create versioned release entry. Commit, tag, push. **Steps (auto-detected version)**: 1. Auto-detect version: v2.1.0 (minor bump, new features detected) 2. Write release entry to CHANGELOG.md 3. `git add CHANGELOG.md` 4. `git commit -m "Release v2.1.0"` 5. `git tag -a v2.1.0 -m "Release v2.1.0 - Dark mode and CSV export"` 6. `git push --follow-tags` **Steps (explicit version)**: Same workflow, but skip auto-detection and use the provided version directly (e.g., `v2.0.0`). **Output**: Released vX.Y.Z, tagged, and pushed to remote. </example> <example> **User request**: "Add this week's changes to the changelog" **Mode**: Update **Action**: Run `git log --since="7 days ago"`, categorize, append to Unreleased section. Commit. **Output**: Updated CHANGELOG.md with new entries under `## [Unreleased]` and committed. </example>

<example> **用户请求**：`/changelog`（无参数，无现有CHANGELOG.md） **模式**：更新 **操作**：未找到CHANGELOG.md。从完整git历史生成。提交。 **步骤**: 1. 从所有提交记录生成CHANGELOG.md 2. `git add CHANGELOG.md` 3. `git commit -m "Add changelog from git history"` **输出**：已创建CHANGELOG.md并提交。准备就绪后可运行`/changelog push`进行推送。 </example> <example> **用户请求**：`/changelog`（存在现有CHANGELOG.md，上一个标签后有新提交） **模式**：更新 **操作**：在Unreleased章节添加新条目。提交。 **步骤**: 1. 更新CHANGELOG.md，添加新的Unreleased条目 2. `git add CHANGELOG.md` 3. `git commit -m "Update changelog with recent changes"` **输出**：已更新Unreleased章节并提交。 </example> <example> **用户请求**：`/changelog push` **模式**：推送 **操作**：检查Unreleased章节中是否有未记录的新提交。必要时补全章节内容。提交并推送。 **步骤**: 1. 发现3条未记录的提交，添加到Unreleased章节 2. `git add CHANGELOG.md` 3. `git commit -m "Update changelog with recent changes"` 4. `git push` **输出**：已向Unreleased章节添加3条条目，完成提交并推送到远程仓库。 </example> <example> **用户请求**：`/changelog release`或`/changelog release v2.0.0` **模式**：发布 **操作**：根据提交类型自动检测版本，或使用用户指定的版本。创建版本发布条目。提交、打标签、推送。 **步骤（自动检测版本）**: 1. 自动检测版本：v2.1.0（次版本升级，检测到新功能） 2. 向CHANGELOG.md写入发布条目 3. `git add CHANGELOG.md` 4. `git commit -m "Release v2.1.0"` 5. `git tag -a v2.1.0 -m "Release v2.1.0 - Dark mode and CSV export"` 6. `git push --follow-tags` **步骤（指定版本）**：工作流相同，但跳过自动检测，直接使用用户提供的版本（如`v2.0.0`）。 **输出**：已发布vX.Y.Z，完成打标签并推送到远程仓库。 </example> <example> **用户请求**："将本周的变更添加到变更日志" **模式**：更新 **操作**：执行`git log --since="7 days ago"`，分类后追加到Unreleased章节。提交。 **输出**：已更新CHANGELOG.md，在`## [Unreleased]`下添加新条目并提交。 </example>

References

参考文档

File	Content
`references/changelog_format.md`	Full Keep a Changelog spec, Conventional Commits mapping, writing style guide, anti-patterns, release workflow reference, complete example

文件	内容
`references/changelog_format.md`	完整的Keep a Changelog规范、Conventional Commits映射、写作风格指南、反模式、发布工作流参考、完整示例