变更日志

记录每次值得说明的变更，标出破坏性改动，并说明受影响者和应对方式。

适用场景

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

记录与政策： 按日期记录改了什么，放在这里；版本如何工作、如何迁移，放在各自页面，并从每条破坏性条目链接过去。
两种体裁，按读者关注点选择：
- 按日期分标题 —— 适用于持续交付的产品界面。每次发布一个日期分节；条目按变更命名。
- 按版本分标题 —— 适用于版本化产物（SDK、命名的 API 版本）：每个版本一个分节（## [2.14.0] — 2026-06-18，库还要有 Unreleased 分节）。下面的条目规则在每个版本分节内部适用。维护者的问题 “2.13 到 2.14 之间改了什么？” 在按日期的日志里无法回答 —— 如果读者会固定版本，就按版本分标题。

变更日志不是：

提交日志。 变更日志是写给人类（如今也写给智能体）的 —— 精挑细选、收益优先的条目，而不是合并消息的倾倒场。一项变更如果不值得解释，就不值得列出。
发布营销。 发布文章用于说服；变更日志条目用于告知。如果有发布文章，从条目链接过去 —— 不要用它替换条目。
迁移指南。 条目说明某事会破坏什么，并链接出去；逐步迁移过程是一篇操作指南（大型迁移可写专门的迁移指南）。

标题与描述

页面标题：“变更日志” —— 固定的、预期的字符串。
条目标题：变更本身，具体且自成一体。 “重试退避现在可按端点配置” —— 不要 “投递改进”（什么都没说），也不要裸版本号（版本是分节标题，不是条目）。
页面描述公式：“产品的每次重要变更，按日期记录，并标出破坏性变更。”

脚手架生成本页

安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：

npx @cloudflare/nimbus-docs add content-changelog
yarn nimbus-docs add content-changelog
pnpm nimbus-docs add content-changelog
bunx @cloudflare/nimbus-docs add content-changelog

组件建议

分节标题（日期或版本）+ 条目小标题是结构。破坏性标记以粗体放在条目正文开头（**Deprecated · Breaking, effective 2026-09-18**）—— 这是扫读者和订阅源读者第一眼看到的内容，又不会污染标题锚点。在渲染页面中，标题行上的 Badge 组件可以呼应它。
分类标签（六个标准分类：Added / Changed / Deprecated / Removed / Fixed / Security）作为一致的粗体前缀 —— 让页面既能用眼睛筛选，也能被机器筛选。
不适合： Steps（迁移步骤住在链接的指南里）、卡片、截图（改为链接到展示新 UI 的文档 —— 变更日志里的截图会原地永久腐坏）。

结尾

变更日志没有结尾；它只累积。契约放在顶部（政策链接、订阅渠道）以及每条条目里（链接到描述新状态的页面）。

绝不悄悄改写已发布的条目。如果某条后来发现写错了，比如漏标了破坏性变更，就修改它，并发布一条带日期的更正，让按版本和按日期扫读的读者都能看到。

阈值

条目正文 ≤ 3 句。 更深的细节放在链接的详情页、迁移指南或发布文章里。
改变已记录行为的条目要链接到更新后的文档页。 Fixed 和 Security 条目在有对应页面时链接到相关参考或故障排查页 —— 修复了文档从未记录的行为，无处可指，这没关系。
每条破坏性/弃用条目都要写明：影响谁、该做什么、日期。 缺任何一项，就不该发布。

链接与时效

条目要深链到稳定的文档锚点，这也是参考锚点永不移动的又一个原因。条目标题也是永久链接，所以要保持稳定。

发布条目和更新它所链接的页面是同一个动作。宣布某个字段的条目，若参考页还没展示该字段，就是在记录一个不存在的产品。

智能体说明

变更日志是纠正先验知识的地方：已弃用的东西在训练数据里还活着，所以 Deprecated/Removed 条目正是阻止智能体推荐它们的内容。把它们写成智能体可执行的平铺陈述句：“attempt_count 已弃用；请使用 attempt。”
日期用 ISO 格式（2026-06-18）；“上个月” 在被检索的块里毫无意义。
每条条目自成一体：完整字段名、完整功能名 —— 被单独检索的条目必须单独看也讲得通。
个性永远不能替代事实。没有具体信息的俏皮话是空话，读者和智能体都无法据此行动；想要语气，就加在事实之后，而不是代替事实。

检查清单

建议性 —— 供作者或智能体自检，永不作为构建闸门：