writing-changelogs

编写变更日志

必备背景知识：technical-writing 技能（硬性规则、真实性规则、风格）。

概述

变更日志记录的是变更，而非当前状态；迁移文档和发布说明也是以变更为主题的文档类型。它具有历史记录性质：条目永不改写，只能追加。

何时调用，何时不调用

在发布有意义的变更后调用，例如功能、规模较大的修复或移除；编写发布说明时；或总结已发布的内容时。对于琐碎的编辑（大致不超过三个改动文件或三个提交），不要调用；绝不可改写或删除现有条目。

规则

• 每项已发布的变更写一条条目，最新的排在最前；使用 ISO 日期；存在版本时按版本分组。
• 文件采用标准类别时，使用：Added / Changed / Deprecated / Fixed / Removed / Security。Deprecated 条目应注明移除日期和替代方案。
• 破坏性变更放在条目开头，置于各类别之上，并注明所需迁移操作（存在迁移指南时附上链接）。
• 优先说明用户可见的影响，而非实现细节。
• 使用现在时和主动语态，不使用读者可能不熟悉的术语。
• 将相关变更归为一组，绝不重复已有条目。
• 记录移除事项，不要只记录新增事项。
• 发布说明是面向受众的同一组事实的精简版本：说明变更内容、受影响对象以及需要采取的行动。变更日志面向工程师，发布说明面向系统用户。两者依据相同的信息来源，且绝不可相互矛盾。

条目格式

**文档类型例外：**下文要求的加粗引导语优先于共享规则中禁止使用加粗引导语项目符号的规定。此例外仅适用于变更日志结果，以及指定的已知问题、延期事项和刻意省略类别。其他地方仍禁止反复使用“标签-值”项目符号。

用加粗引导语说明结果，然后说明根本原因，再说明修复，并在行内使用准确名称：

- **Reference-to-video routing fixed.** The resolver only knew three operation
  kinds, so requests with reference media routed to image-to-video. A
  `hasReferenceMedia()` check now gives reference-to-video a higher-priority
  branch.

Fixed 条目应说明故障模式，而非差异内容。加粗引导语应体现对用户的影响，方便读者快速判断变更列表中各项的优先级。

诚实约定

以下三种条目类型能让变更日志可供引用：

• 已知问题：在本次变更中发现但未修复的问题，并明确标注为已知问题。
• 延期事项：仍待完成的工作（“还需一次部署才能恢复 webhook 密钥”）。
• 刻意省略：按类别说明，避免之后再次争论同一项省略，或将其误认为疏忽。

除非确实完成并检查了对应操作，否则绝不可标记为已实现、已部署或已验证。应区分已实现（在代码库中）、已部署（已上线）和经外部验证。

交接 / 完成情况总结

向审核者或操作人员移交已完成的工作时，按以下顺序涵盖这些部分：

1. 此项工作的目的
2. 已发布的内容
3. 审核时应关注之处（审核者在评判前必须了解的决策）
4. 验证状态：准确的命令及其结果，绝不能只给一个勾号
5. 诚实说明注意事项及出错之处
6. 剩余风险和切勿采取的操作
7. 当前状态及待办事项（已合并但未推送、迁移，以及执行顺序错误会造成何种后果）