跳到主要内容
版本:Next

变更日志条目规范

这份规范说明「更新日志」里的每一条从哪来、长什么样、由谁维护。年度文件(如 2026.md)整体由脚本生成,本页是唯一的人工入口。

记录范围​

记不记
已合并到主干的文档新增 / 修订 / 删除草稿、正在写的分支、未合并的改动
提交信息里显式声明的勘误与破坏性更正纯样式、纯配置、构建脚本调整
每条涉及的文件、标签、对应代码版本逐字 diff(那是 git log 的职责,这里只给结论)

为什么不记草稿:更新日志是给订阅者和回头查证的人看的,只有已合并的内容才谈得上「以此为准」。把进行中的工作写进去,等于让人按未定稿的结论写代码。

条目结构​

## 2026-11-13

### 新增 · 站点导览

- 文件:[站点导览](/)
- 版本:5.8 | 标签:导览
- 对比:[8cc4a77](https://github.com/<owner>/<repo>/commit/8cc4a77)

四层信息各自承担一件事:

  1. 日期 H2 —— 按提交日期分组,倒序(新的在上)。
  2. 条目 H3 —— 分类 · 文档标题。标题文本即锚点,所以每条都能单独发给别人(#新增--站点导览)。
  3. 元信息三行 —— 文件(点进去看现行内容)、版本与标签(判断这条是否适用于你手上的版本)、对比(跳到那次提交看真实 diff)。
  4. 分类 —— 决定这条该不该看,判定规则见下。

分类怎么判定​

机器能判断「文件是新增还是修改」,判断不了「这次修改是不是纠正了旧结论」。所以分两类来源:

分类来源判定
新增git 状态文件出现(A)
修订git 状态文件内容变化(M / R)
破坏性更正提交信息前缀文件被删除(D),或提交信息以 [破坏性更正] 开头
勘误提交信息前缀提交信息以 [勘误] 开头

前缀与 site.config.js 里 changelog.kinds 的值逐字比对,所以改配置里的词就等于改前缀词。条目标题取的是文档标题而不是提交信息,前缀不会污染正文。

写法示例:

[勘误] 修正 StreamableManager 回调线程归属的结论
[破坏性更正] 可见性标记的口径改为按视图索引

生成方式​

npm run changelog # 重新生成全部年度文件(中英各一份)
npm run changelog:check # 只检查:有未记录的提交就退出码 1(CI 用)
npm run changelog -- --dry-run # 打印将要写入的内容,不落盘
npm run changelog -- --since=2026-01-01 # 只回溯某个时间点之后的提交

三条硬规则:

  1. 年度文件不要手改。生成器会整篇重写 frontmatter 与正文,手工修改在下一次生成时消失。
  2. 新年度自动开文件。跨年后第一次提交会自动产生 2027.md,sidebar_position 按年份倒序自动算,不需要改任何配置。
  3. 对比链接按需生成。site.config.js 的 repo.owner / repo.name 为空时不输出任何 compare 链接——宁可没有,也不给死链。填好这两项后重新生成即可补上。

与订阅的关系​

变更日志是邮件汇总的唯一输入源:订阅脚本读年度文件里当天的条目,按 tags 分组投递。所以条目的三行元信息不是装饰——缺文件或缺标签的条目会在汇总里降级成一行标题,信息量立刻变少。想让订阅者一眼看懂,就写清分类与标题。

与版本化的关系​

历史版本(如 5.8)的页面是快照,不会随主干的修订变化;更新日志只记录主干。两者冲突时:先看你读的是哪个版本的页面,再看那条记录对应的版本字段。