# CHANGELOG 文档规范 > 本文档定义项目 CHANGELOG 的格式、维护规则与版本管理约束，确保变更历史清晰、可追溯、可验证。 --- ## 1. 基本规则 ### 1.1 存放位置 - **主文件**：项目根目录 `CHANGELOG.md` - **存档**（可选）：`docs/CHANGELOG_ARCHIVE.md` 或 `docs/CHANGELOG/` ### 1.2 文件格式与编码 - **格式**：Markdown（`.md`） - **编码**：UTF-8 - **行尾**：LF（Unix 风格） - **版本参考**：遵循 [Keep a Changelog](https://keepachangelog.com/) 规范，中文本地化 --- ## 2. 版本结构规范 ### 2.1 基础格式 ```markdown # CHANGELOG 本文档记录项目的版本发布、功能变更、问题修复与重要更新。 ## [版本号] - 发布日期 ### Added - 新增功能描述（要点形式） - 新增功能描述 ### Changed - 变更的功能或行为 - 变更的功能或行为 ### Fixed - 修复的 bug - 修复的 bug ### Deprecated - 标记为弃用的功能 ### Removed - 删除的功能 ### Security - 安全相关的修复与更新 --- ## [版本号] - 发布日期 ... ``` ### 2.2 版本号格式遵循 [语义化版本](https://semver.org/)（Semantic Versioning）： ``` v..[-][+] ``` **示例**： - `v1.0.0` - 首个正式版本 - `v1.1.0` - 新增功能（向后兼容） - `v1.0.1` - 修复 bug（向后兼容） - `v2.0.0` - 重大破坏性变更 - `v1.0.0-beta.1` - 预发布版本 - `v1.0.0-beta.1+20260419` - 包含构建元数据 --- ## 3. 版本条目必填字段 ### 3.1 版本头信息每个版本必须包含： | 字段 | 格式 | 说明 | |---|---|---| | 版本号 | `v X.Y.Z` | 遵循语义化版本 | | 发布日期 | `YYYY-MM-DD` | 发布的实际日期（ISO 8601） | | 状态（可选） | `[RELEASED]` / `[UNRELEASED]` | `[UNRELEASED]` 表示开发中版本 | **示例**： ```markdown ## [v1.2.0] - 2026-04-19 ## [Unreleased] ``` ### 3.2 变更分类使用以下标准分类，**按此顺序排列**（有内容才写）： 1. **Added** - 新增功能 2. **Changed** - 现有功能的变更（行为、性能、API 调整等） 3. **Deprecated** - 标记为弃用但仍可用的功能（需注明何时移除） 4. **Removed** - 已删除的功能、API、参数等 5. **Fixed** - Bug 修复 6. **Security** - 安全相关的修复与警告 ### 3.3 变更描述要求每条变更需满足： - **格式**：简明要点形式（短句或单句），首字母大写 - **指向性**：说明变更的**内容**与**影响**，不开玩笑 - **可追溯性**：关键变更需关联 Git Commit Hash（7 位）或 Issue/PR 编号 **示例**： ```markdown ### Added - 支持 YAML 配置文件格式 (#127) - 新增 `--verbose` 命令行选项，用于详细日志输出 - 用户认证模块，支持 OAuth 2.0 (commit: a1b2c3d) ### Fixed - 修复登录页 Safari 兼容性问题 (issue: #345) - 修复在 Windows 路径包含特殊字符时配置读取失败 (PR #456) ### Deprecated - API endpoint `/api/v1/users` 将在 v2.0.0 中移除，请迁移至 `/api/v2/users` ``` --- ## 4. 版本维护流程 ### 4.1 开发阶段（Unreleased） 1. **初始化**：新版本开发开始时，在 CHANGELOG.md 顶部创建 `[Unreleased]` 条目。 2. **持续维护**：每次功能开发/修复完成后，**立即**添加到对应分类下。 3. **禁止忽视**：不允许在发布时才补写，必须边开发边记录。 **示例**： ```markdown # CHANGELOG ## [Unreleased] ### Added - 用户权限管理模块 - 新增 JSON Schema 验证器 ### Fixed - 修复数据库连接池泄漏问题 ## [v1.0.0] - 2026-04-01 ... ``` ### 4.2 发布阶段版本发布前： 1. **更新版本号**：将 `[Unreleased]` 改为 `[vX.Y.Z] - YYYY-MM-DD`。 2. **验证完整性**：检查所有变更是否都已记录。 3. **生成 Git Tag**： ```bash git tag -a vX.Y.Z -m "Release vX.Y.Z" [commit-hash] git push origin vX.Y.Z ``` 4. **创建新的 Unreleased 条目**：为下一版本开发做准备。 **发布示例**： ```markdown # CHANGELOG ## [Unreleased] ### Added - [开发中的新功能登记在此] ## [v1.1.0] - 2026-04-19 ### Added - 用户权限管理模块 - 新增 JSON Schema 验证器 ### Fixed - 修复数据库连接池泄漏问题 ## [v1.0.0] - 2026-04-01 ... ``` --- ## 5. 与 Git Commit 的关联规则 ### 5.1 关联格式在 CHANGELOG 条目中，用以下格式指向 Git 提交： | 类型 | 格式 | 示例 | |---|---|---| | Git Commit Hash（7 位） | `(commit: abc1234)` | `修复缓存失效问题 (commit: f3e2c1d)` | | Issue 编号 | `(#123)` 或 `(issue: #123)` | `新增登录功能 (#456)` | | Pull Request | `(PR #789)` 或 `(pull: #789)` | `重构数据库层 (PR #789)` | | 多关联 | 用逗号分隔 | `重要变更 (commit: a1b2c3d, PR #123)` | ### 5.2 Commit Message 规范发起 Commit 时，推荐使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式，自动化支持 CHANGELOG 生成： ``` ():