docs-changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs Changelog

文档变更日志

Write a new changelog entry by reviewing commits since the last documented entry, categorizing changes, and appending a well-written entry in Keep a Changelog format.

通过查看上次已记录条目之后的提交、对变更进行分类，并以Keep a Changelog格式追加撰写规范的条目，来创建新的变更日志条目。

Workflow

工作流程

1. Find the changelog file

1. 查找变更日志文件

Search for the changelog in common locations:

CHANGELOG.md
changelog.md
docs/changelog.md
docs/CHANGELOG.md
src/pages/changelog.md
src/content/changelog.mdx
content/changelog.md

Use

glob

with patterns like

**/changelog.{md,mdx}

and

**/CHANGELOG.{md,mdx}

if not found in standard locations. If multiple candidates exist, ask the user which one to use.

在常见位置搜索变更日志：

CHANGELOG.md
changelog.md
docs/changelog.md
docs/CHANGELOG.md
src/pages/changelog.md
src/content/changelog.mdx
content/changelog.md

如果在标准位置未找到，可使用

glob

搭配

**/changelog.{md,mdx}

和

**/CHANGELOG.{md,mdx}

这类模式进行搜索。如果存在多个候选文件，请询问用户使用哪一个。

2. Parse the last entry

2. 解析上次条目

Read the changelog file and extract the most recent version header. The header format is:

undefined

读取变更日志文件并提取最新的版本标题。标题格式为：

undefined

[X.Y.Z] - YYYY-MM-DD


Extract:
- **Version number** (e.g., `1.2.0`) — for determining the next version
- **Date** (e.g., `2025-01-15`) — for scoping the git log

If the changelog is empty or has only an `[Unreleased]` header, use the repo's earliest tag or first commit as the boundary.


提取以下信息：
- **版本号**（例如：`1.2.0`）——用于确定下一个版本
- **日期**（例如：`2025-01-15`）——用于限定Git日志的范围

如果变更日志为空或仅包含`[Unreleased]`标题，则使用仓库最早的标签或首次提交作为边界。

3. Gather commits

3. 收集提交记录

Run:

bash

git log --oneline --no-merges --after="YYYY-MM-DD" HEAD

Where

YYYY-MM-DD

is the date from the last changelog entry. Also check tags:

bash

git tag -l --sort=-creatordate | head -5

If there's a tag newer than the last changelog entry, use that as the new version number. Otherwise, ask the user what version this entry should be.

运行以下命令：

bash

git log --oneline --no-merges --after="YYYY-MM-DD" HEAD

其中

YYYY-MM-DD

是上次变更日志条目中的日期。同时检查标签：

bash

git tag -l --sort=-creatordate | head -5

如果存在比上次变更日志条目更新的标签，则将该标签作为新版本号。否则，询问用户本次条目应使用哪个版本。

4. Categorize changes

4. 对变更进行分类

Review each commit and assign it to one Keep a Changelog category:

Category	What belongs here
Added	New features, new pages, new API endpoints
Changed	Updates to existing functionality, behavior changes, dependency updates
Deprecated	Features marked for future removal
Removed	Deleted features, removed pages, dropped support
Fixed	Bug fixes, typo corrections, broken link repairs
Security	Vulnerability patches, security improvements

Categorization rules:

Read the diff when a commit message is ambiguous — the code tells the truth
Group related commits into a single bullet (e.g., three typo-fix commits become one "Fixed typos across documentation" entry)
Skip commits that are purely internal (CI config, linting, formatting-only) unless they affect user-visible behavior
Skip merge commits and version bump commits

查看每个提交，并将其归入Keep a Changelog的某一类别：

类别	包含内容
Added（新增）	新功能、新页面、新API端点
Changed（变更）	现有功能更新、行为变更、依赖项更新
Deprecated（弃用）	标记为未来将移除的功能
Removed（移除）	删除的功能、移除的页面、终止的支持
Fixed（修复）	漏洞修复、拼写错误修正、失效链接修复
Security（安全）	漏洞补丁、安全改进

分类规则：

当提交信息不明确时查看代码差异——代码才是真相
将相关提交归为单个项目符号（例如：三次拼写错误修复提交合并为“修复了文档中的多处拼写错误”条目）
跳过纯内部的提交（CI配置、仅代码检查或格式化的提交），除非它们会影响用户可见的行为
跳过合并提交和版本号更新提交

5. Write the entry

5. 撰写条目

Insert the new entry directly below the

# Changelog

header (or below

## [Unreleased]

if present). Use this exact structure — omit any category section that has no items:

markdown

undefined

将新条目直接插入到

# Changelog

标题下方（如果存在

## [Unreleased]

，则插入到其下方）。使用以下精确结构——省略没有内容的类别部分：

markdown

undefined

[X.Y.Z] - YYYY-MM-DD

Added

Brief, human-readable description of what was added

简洁、易于人类阅读的新增内容描述

Changed

Brief description of what changed

简洁的变更内容描述

Fixed

Brief description of what was fixed


**Writing rules:**
- Each bullet is one sentence, starting with a past-tense verb (Added, Updated, Fixed, Removed)
- Write for the end user of the documentation site, not for developers
- Link to relevant pages or PRs where helpful: `Fixed broken link on [Getting Started](/docs/getting-started) page`
- Keep entries scannable — no paragraphs, no sub-bullets
- Use the project's existing tone (scan prior entries to match)
- Today's date for the entry date unless the user specifies otherwise

简洁的修复内容描述


**撰写规则：**
- 每个项目符号为一句话，以过去式动词开头（Added、Updated、Fixed、Removed）
- 面向文档站点的最终用户撰写，而非开发者
- 如有帮助，可链接到相关页面或PR：`Fixed broken link on [Getting Started](/docs/getting-started) page`（修复了[快速入门](/docs/getting-started)页面上的失效链接）
- 保持条目易于扫描——不要使用段落，不要使用子项目符号
- 匹配项目现有的语气（查看之前的条目以保持一致）
- 除非用户指定，否则条目日期使用当前日期

6. Verify

6. 验证

After writing the entry:

Confirm the entry is in reverse chronological order (newest first)
Check that version link references at the bottom of the file are updated if the project uses them (e.g.,
```
[1.3.0]: https://github.com/org/repo/compare/v1.2.0...v1.3.0
```
)
Read the final file to ensure formatting is clean

Present the new entry to the user for review before considering the task complete.

撰写完条目后：

确认条目按倒序时间排列（最新的在前）
如果项目使用版本链接引用，请检查文件底部的版本链接引用是否已更新（例如：
```
[1.3.0]: https://github.com/org/repo/compare/v1.2.0...v1.3.0
```
）
通读最终文件，确保格式整洁

在完成任务前，将新条目提交给用户审核。