changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog

Format specification for CHANGELOG.md based on Keep a Changelog 1.1.0.

基于 Keep a Changelog 1.1.0 的 CHANGELOG.md 格式规范。

Language Requirement (Mandatory)

语言要求（强制性）

All changelog content MUST be written in English.
If source information is provided in another language, translate it to English.
Do not mix languages within the same changelog.

所有变更日志内容必须使用英文编写。
如果源信息为其他语言，需将其翻译为英文。
同一变更日志中不得混合使用多种语言。

Quick Reference

快速参考

File Header

文件头部

markdown

undefined

markdown

undefined

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

undefined

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

undefined

Section Structure

章节结构

markdown

undefined

markdown

undefined

[Unreleased]

Added

New feature description

New feature description

[1.0.0] - 2024-01-15

Added

Feature A
Feature B

Feature A
Feature B

Changed

Modified behavior X

Modified behavior X

Fixed

Bug fix Y

undefined

Bug fix Y

undefined

Types of Changes

变更类型

Type	Purpose
`Added`	New features
`Changed`	Changes in existing functionality
`Deprecated`	Soon-to-be removed features
`Removed`	Now removed features
`Fixed`	Bug fixes
`Security`	Vulnerabilities

类型	用途
`Added`	新增功能
`Changed`	现有功能变更
`Deprecated`	即将移除的功能
`Removed`	已移除的功能
`Fixed`	漏洞修复
`Security`	安全漏洞修复

Format Rules

格式规则

Version Header

版本头部

markdown

undefined

markdown

undefined

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


- Version in brackets, linked to comparison
- Date in ISO 8601 format (YYYY-MM-DD)


- 版本号放在方括号中，并关联至对比链接
- 日期采用 ISO 8601 格式（YYYY-MM-DD）

Date-Based Versioning (Alternative)

基于日期的版本控制（替代方案）

For projects using date-based versioning instead of semver:

markdown

undefined

对于使用基于日期而非 semver 进行版本控制的项目：

markdown

undefined

[YYYY-MM-DD]


Use current date instead of `[Unreleased]`. This project uses date-based versioning.


使用当前日期替代 `[Unreleased]`。本项目采用基于日期的版本控制。

Yanked Releases

撤回的版本

markdown

undefined

markdown

undefined

[0.0.5] - 2014-12-13 [YANKED]


Use when version was pulled due to serious bug or security issue.


当版本因严重漏洞或安全问题被撤回时使用。

Comparison Links (at file end)

对比链接（文件末尾）

markdown

[unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0

markdown

[unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/user/repo/releases/tag/v0.9.0

Guiding Principles

指导原则

For humans, not machines — Write clear, readable entries
Entry for every version — Document all releases
Group same types — Keep Added/Changed/Fixed together
Linkable versions — Use comparison links
Latest first — Reverse chronological order
Show release dates — Use ISO 8601 format
State versioning scheme — Mention Semantic Versioning if used

面向人类而非机器 — 编写清晰、易读的条目
每个版本都有记录 — 记录所有发布版本
同类变更分组 — 将 Added/Changed/Fixed 等类型的变更放在一起
版本可链接 — 使用对比链接
最新版本优先 — 采用逆 chronological 顺序
显示发布日期 — 使用 ISO 8601 格式
声明版本控制方案 — 若使用语义化版本控制需明确提及

Complete Example

完整示例

markdown

undefined

markdown

undefined

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

New authentication method

New authentication method

[1.2.0] - 2024-01-20

Added

User profile page
Export to CSV functionality

User profile page
Export to CSV functionality

Changed

Improved loading performance by 40%

Improved loading performance by 40%

Deprecated

Legacy API endpoint
```
/api/v1/users
```
(use
```
/api/v2/users
```
)

Legacy API endpoint
```
/api/v1/users
```
(use
```
/api/v2/users
```
)

Fixed

[1.1.0] - 2024-01-10

Added

Dark mode support

Dark mode support

Security

Fixed XSS vulnerability in comment field

Fixed XSS vulnerability in comment field

[1.0.0] - 2024-01-01

Added

Initial release with core features
User registration and login
Dashboard with analytics

undefined

Initial release with core features
User registration and login
Dashboard with analytics

undefined

Bad Practices

不良实践

Commit log diffs

提交日志差异

Don't dump git log into changelog:

Full of noise (merge commits, obscure titles)
Not human-readable
Mixes important and trivial changes

不要将 git log 直接导入变更日志：

包含大量冗余信息（合并提交、模糊标题）
不便于人类阅读
混合重要和琐碎变更

Ignoring deprecations

忽略弃用通知

Don't skip deprecation notices:

Users need to know what will break
Document deprecations before removals
List breaking changes clearly

不要跳过弃用通知：

用户需要了解哪些功能即将失效
在移除功能前先记录弃用信息
清晰列出破坏性变更

Confusing dates

日期格式模糊

Don't use regional date formats:

Use ISO 8601:
```
YYYY-MM-DD
```
Avoids ambiguity (is 01/02/2024 Jan 2 or Feb 1?)

不要使用区域化日期格式：

使用 ISO 8601 格式：
```
YYYY-MM-DD
```
避免歧义（01/02/2024 是1月2日还是2月1日？）

Inconsistent changes

变更记录不一致

Don't document only some changes:

Changelog should be single source of truth
Important changes must be mentioned
Consistently updated

不要只记录部分变更：

变更日志应作为唯一的事实来源
必须提及重要变更
保持持续更新

Writing Tips

写作技巧

Good Entry Examples

优秀条目示例

markdown

undefined

markdown

undefined

Added

OAuth2 authentication with Google and GitHub providers
Rate limiting for API endpoints (100 req/min)

OAuth2 authentication with Google and GitHub providers
Rate limiting for API endpoints (100 req/min)

Changed

Database queries now use prepared statements for better security
Upgraded dependency
```
lodash
```
from 4.17.20 to 4.17.21

Database queries now use prepared statements for better security
Upgraded dependency
```
lodash
```
from 4.17.20 to 4.17.21

Fixed

Memory leak in WebSocket connection handler
Race condition in concurrent file uploads

undefined

Memory leak in WebSocket connection handler
Race condition in concurrent file uploads

undefined

Entry Guidelines

条目编写指南

Review current git changes (diff or changed files list) before drafting; ensure all material changes are covered.
Start with verb or noun describing the change
Be specific (mention affected component/endpoint)
Reference issue/PR numbers when relevant:
```
(#123)
```
Keep entries concise but informative
Omit empty sections (do not include a section header if there are no entries for it)

起草前查看当前 git 变更（差异或已修改文件列表）；确保所有重大变更都被涵盖。
以描述变更的动词或名词开头
具体明确（提及受影响的组件/端点）
相关时引用问题/PR 编号：
```
(#123)
```
条目简洁但信息完整
省略空章节（如果没有对应条目，不要包含章节标题）

File Naming

文件命名

Required:

CHANGELOG.md

(uppercase). Do not use lowercase or alternative names.

Do not use alternative filenames.

必须使用：

CHANGELOG.md

（大写）。不要使用小写或其他替代名称。

禁止使用其他文件名。

GitHub Releases vs CHANGELOG.md

GitHub Releases 与 CHANGELOG.md

Aspect	GitHub Releases	CHANGELOG.md
Portability	GitHub-only	Universal
Discoverability	Less visible	Standard location
Version control	Separate UI	In repository
Diff links	Manual setup	Easy to add

GitHub Releases can complement but shouldn't replace CHANGELOG.md.

方面	GitHub Releases	CHANGELOG.md
可移植性	仅支持GitHub	通用格式
可发现性	可见性较低	标准存储位置
版本控制	独立UI界面	包含在代码仓库中
差异链接	需手动设置	易于添加

GitHub Releases 可以作为补充，但不应替代 CHANGELOG.md。

Conventional Commits Integration

约定式提交集成

Changelogs work best with Conventional Commits format:

Commit Type	Changelog Section
`feat:`	Added
`fix:`	Fixed
`perf:`	Changed
`refactor:`	Changed
`docs:`	(often omitted)
`BREAKING CHANGE`	Highlight in Changed
Security fix	Security
`revert:`	Removed or Fixed

变更日志与 Conventional Commits 格式配合使用效果最佳：

提交类型	变更日志章节
`feat:`	Added
`fix:`	Fixed
`perf:`	Changed
`refactor:`	Changed
`docs:`	（通常省略）
`BREAKING CHANGE`	在Changed中突出显示
Security fix	Security
`revert:`	Removed 或 Fixed

Automated Generation

自动生成

Tools that parse Conventional Commits and generate changelogs:

See commits skill for commit message format.

可解析约定式提交并生成变更日志的工具：

有关提交消息格式，请查看 commits skill。

Workflow Integration

工作流集成

Unreleased Section Pattern

未发布章节模式

Add changes to
```
## [Unreleased]
```
during development
At release time, rename to
```
## [X.Y.Z] - YYYY-MM-DD
```
Create new empty
```
## [Unreleased]
```
section
Add comparison link for new version

开发过程中将变更添加至
```
## [Unreleased]
```
发布时，将其重命名为
```
## [X.Y.Z] - YYYY-MM-DD
```
创建新的空
```
## [Unreleased]
```
章节
为新版本添加对比链接

Pre-commit Checklist

提交前检查清单

Critical Prohibitions

严格禁止事项

Do not use git log as changelog
Do not omit breaking changes or deprecations
Do not use ambiguous date formats
Do not leave changelog inconsistently updated
Do not forget to update Unreleased → version at release
Do not write changelog entries in any language other than English

不要将 git log 作为变更日志
不要忽略破坏性变更或弃用信息
不要使用模糊的日期格式
不要让变更日志更新不一致
发布时不要忘记将 Unreleased 转换为对应版本
不要使用英文以外的语言编写变更日志条目

README Synchronization

README 同步

After writing changelog, review the project's main README.md:

Check for outdated information — features, skills, tools lists
Add new entries — if changelog introduces new skills, features, or components
Remove deprecated items — if changelog removes functionality
Update descriptions — if changelog changes existing functionality

What to sync:

Skills/features tables
Compatibility lists
Installation instructions
Links and references

What NOT to sync:

Changelog content itself (no duplication)
Version history
Detailed change descriptions

Do NOT mention README.md updates in CHANGELOG — README synchronization is implied and should not be logged as a separate change.

编写完变更日志后，回顾项目的主 README.md：

检查过时信息 — 功能、技能、工具列表
添加新条目 — 如果变更日志引入了新技能、功能或组件
移除已弃用项 — 如果变更日志移除了某些功能
更新描述 — 如果变更日志修改了现有功能

需要同步的内容：

技能/功能表格
兼容性列表
安装说明
链接和参考资料

不需要同步的内容：

变更日志内容本身（避免重复）
版本历史
详细变更描述

不要在 CHANGELOG 中提及 README.md 更新 — README 同步是隐含操作，不应作为单独变更记录。

链接

Official specification: https://keepachangelog.com/en/1.1.0/
Semantic Versioning: https://semver.org/spec/v2.0.0.html
Related: commits skill — Conventional Commits format

官方规范：https://keepachangelog.com/en/1.1.0/
语义化版本控制：https://semver.org/spec/v2.0.0.html
相关链接：commits skill — 约定式提交格式

Templates

模板

CHANGELOG.template.md — Empty template to start
CHANGELOG.example.md — Complete working example

CHANGELOG.template.md — 用于起步的空模板
CHANGELOG.example.md — 完整的可用示例