变更日志

变更记录指南——带日期、分类的条目标记破坏性变更并深度链接到文档。包含清单和搭建命令。

更新于 Sep 30, 2026查看 Markdown

何时使用

每个产品一个变更日志（或每个明确版本化的接口一个）。两个承重区分：

记录 vs. 策略： 带日期的变更记录在这里；版本化工作方式和迁移方法在它们自己的页面上，从每个破坏性条目链接过去。
两种体裁，按读者关注点选择：
- 按日期开头——用于持续发布的产品接口。按发布日期分节；条目以变更内容为标题。
- 按版本开头——用于版本化的制品（SDK、命名的 API 版本）：按版本分节（## [2.14.0] — 2026-06-18，库项目加一个 Unreleased 章节）。以下的条目规则适用于每个版本章节内部。维护者的问题“2.13 和 2.14 之间有什么变化？“在按日期开头的日志中无法回答——如果读者固定版本，按版本开头。

变更日志不是：

页面标题： “Changelog”——固定的、预期的字符串。
条目标题：变更本身，具体且自成一体。 “Retry backoff is now configurable per endpoint”——不是 “Improvements to delivery”（什么都没说），也不是裸版本号（版本用作章节标题，不是条目标题）。
描述公式（页面）： “产品的每个值得注意的变更，带日期，标记破坏性变更。”

安装指南——你的编码智能体会读取完整的骨架和清单，并将其适配到你的产品：

npx @cloudflare/nimbus-docs add content-changelog

yarn dlx @cloudflare/nimbus-docs add content-changelog

pnpm dlx @cloudflare/nimbus-docs add content-changelog

bunx @cloudflare/nimbus-docs add content-changelog

章节标题（日期或版本）+ 条目子标题是结构。破坏性标记以粗体开启条目正文（**Deprecated · Breaking, effective 2026-09-18**）——扫读者和 feed 阅读器看到的第一件事，不污染标题的锚点。在渲染页面中，标题行上的 Badge 组件可以呼应它。
分类标签（六个标准分类：Added / Changed / Deprecated / Removed / Fixed / Security）作为一致的粗体前缀——它们使页面可按肉眼和机器筛选。
不适用： Steps（迁移步骤在链接的指南中）、Cards、截图（改为链接展示新 UI 的文档——变更日志中的截图会永远原地腐烂）。

变更日志不结束；它累积。契约在顶部（策略链接、订阅频道）和每个条目（链接到描述新状态的页面）。已发布的条目永远不悄悄改写：如果条目被证明有误——一个破坏性变更未标记——修正原条目并发布一个带日期的修正条目，这样按版本扫描的升级者和按时间线阅读的读者都能看到。

条目正文 ≤ 3 句。 超出此深度的内容放在链接的详情页、迁移指南或发布帖中。
改变已记录行为的条目链接到更新后的文档页面。 Fixed 和 Security 条目在存在时链接到相关参考或故障排除页面——文档从未记录过的行为修复没有可指向的地方，这没关系。
每个破坏性/废弃条目包含：受影响者、应对措施、日期。 缺少三者中的任何一个，都不适合发布。

变更日志是站点的新鲜度层——条目深度链接到稳定的文档锚点，这也是参考锚点永远不移动的另一个原因（参考指南）。发布条目和更新它链接的页面是一个动作，而非两个：一个宣布参考中尚未展示的字段的条目记录的是一个不存在的产品。条目标题本身是其他人引用的永久链接——用同样的稳定性规则对待它们。

变更日志是先验纠正接口：废弃的内容在训练数据中延续，所以 Deprecated/Removed 条目是阻止智能体推荐它们的东西。写成智能体可以执行的扁平声明：“attempt_count 已废弃；使用 attempt。”
日期使用 ISO 格式（2026-06-18）；“上个月”在检索到的块中毫无意义。
每个条目自成一体：完整的字段名、完整的功能名——单独检索的条目必须单独有意义。
永远不要用个性替代事实。没有具体内容的俏皮话是任何读者或智能体都无法执行的非陈述；如果想要语感，加在事实之后，而非替代事实。

建议性——供作者或智能体自查，不是构建门禁：