changelog

更新日志

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

语言要求（强制）

• 所有更新日志内容必须用英文书写。
• 如果源信息以其他语言提供，请将其翻译为英文。
• 不要在同一个更新日志中混用语言。

快速参考

文件头

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

章节结构

## [Unreleased]

### Added

- New feature description

## [1.0.0] - 2024-01-15

### Added

- Feature A
- Feature B

### Changed

- Modified behavior X

### Fixed

- Bug fix Y

变更类型

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

格式规则

版本标题

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

• 版本号放在方括号中，并链接到比较
• 日期使用 ISO 8601 格式（YYYY-MM-DD）

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

对于使用基于日期的版本号而非语义化版本号的项目：

## [YYYY-MM-DD]

使用当前日期代替 [Unreleased]。本项目使用基于日期的版本号。

已撤回的发布

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

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

比较链接（位于文件末尾）

[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

指导原则

1. 面向人类，而非机器 — 编写清晰、易读的条目
2. 每个版本都要有条目 — 记录所有发布
3. 将相同类型归为一组 — 将 Added/Changed/Fixed 放在一起
4. 版本可链接 — 使用比较链接
5. 最新在前 — 按时间倒序排列
6. 显示发布日期 — 使用 ISO 8601 格式
7. 说明版本号方案 — 如果使用语义化版本号，请注明

完整示例

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New authentication method

## [1.2.0] - 2024-01-20

### Added

- User profile page
- Export to CSV functionality

### Changed

- Improved loading performance by 40%

### Deprecated

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

### Fixed

- Login timeout issue on slow connections

## [1.1.0] - 2024-01-10

### Added

- Dark mode support

### Security

- 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

[unreleased]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/project/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0

不良实践

提交日志差异

不要将 git log 直接倾倒进更新日志：

• 充满噪声（合并提交、晦涩的标题）
• 不易于人类阅读
• 混淆重要变更与琐碎变更

忽略弃用信息

不要跳过弃用通知：

• 用户需要知道什么将会失效
• 在移除之前先记录弃用信息
• 清晰列出破坏性变更

令人困惑的日期

不要使用地区性日期格式：

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

不一致的变更

不要只记录部分变更：

• 更新日志应当是唯一可信来源
• 重要变更必须提及
• 持续更新

写作提示

优秀条目示例

### Added

- 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

### Fixed

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

条目指南

• 在起草前查看当前 git 变更（diff 或变更文件列表）；确保涵盖所有实质性变更。
• 以描述变更的动词或名词开头
• 要具体（提及受影响的组件/端点）
• 在相关时引用 issue/PR 编号：(#123)
• 保持条目简洁但信息充分
• 省略空章节（如果某个章节没有条目，则不要包含该章节标题）

文件命名

必需：CHANGELOG.md（大写）。不要使用小写或替代名称。

不要使用替代文件名。

GitHub Releases 与 CHANGELOG.md

方面	GitHub Releases	CHANGELOG.md
可移植性	仅限 GitHub	通用
可发现性	可见性较低	标准位置
版本控制	独立界面	位于仓库中
差异链接	手动设置	易于添加

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

Conventional Commits 集成

变更日志最适合搭配 Conventional Commits 格式：

提交类型	变更日志章节
feat:	新增
fix:	修复
perf:	变更
refactor:	变更
docs:	（通常省略）
BREAKING CHANGE	在“变更”中突出显示
安全修复	安全
revert:	移除或修复

自动生成

可解析 Conventional Commits 并生成变更日志的工具：

• conventional-changelog
• semantic-release
• release-please

提交消息格式参见 commits skill。

工作流集成

Unreleased 章节模式

1. 开发期间将变更添加到 ## [Unreleased]
2. 发布时重命名为 ## [X.Y.Z] - YYYY-MM-DD
3. 新建空的 ## [Unreleased] 章节
4. 为新版本添加比较链接

提交前检查清单

发布前：

• 所有重要变更均已记录
• Unreleased 章节已移至版本号下
• 日期以 ISO 8601 格式添加
• 已添加比较链接
• 破坏性变更已突出显示
• 弃用项已记录

关键禁止事项

• 不要使用 git log 作为变更日志
• 不要遗漏破坏性变更或弃用项
• 不要使用含糊的日期格式
• 不要让变更日志更新不一致
• 不要在发布时忘记将 Unreleased → 版本号
• 不要用英语以外的任何语言编写变更日志条目

README 同步

编写变更日志后，检查项目的主 README.md：

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

需要同步的内容：

• 技能/功能表
• 兼容性列表
• 安装说明
• 链接和引用

不需要同步的内容：

• 变更日志内容本身（不要重复）
• 版本历史
• 详细的变更描述

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

链接

• 官方规范：https://keepachangelog.com/en/1.1.0/
• 语义化版本：https://semver.org/spec/v2.0.0.html
• 相关：commits skill — Conventional Commits 格式

模板

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