变更日志条目规范
这份规范说明「更新日志」里的每一条从哪来、长什么样、由谁维护。年度文件(如 2026.md)整体由脚本生成,本页是唯一的人工入口。
记录范围
| 记 | 不记 |
|---|---|
| 已合并到主干的文档新增 / 修订 / 删除 | 草稿、正在写的分支、未合并的改动 |
| 提交信息里显式声明的勘误与破坏性更正 | 纯样式、纯配置、构建脚本调整 |
| 每条涉及的文件、标签、对应代码版本 | 逐字 diff(那是 git log 的职责,这里只给结论) |
为什么不记草稿:更新日志是给订阅者和回头查证的人看的,只有已合并的内容才谈得上「以此为准」。把进行中的工作写进去,等于让人按未 定稿的结论写代码。
条目结构
## 2026-11-13
### 新增 · 站点导览
- 文件:[站点导览](/)
- 版本:5.8 | 标签: 导览
- 对比:[8cc4a77](https://github.com/<owner>/<repo>/commit/8cc4a77)
四层信息各自承担一件事:
- 日期 H2 —— 按提交日期分组,倒序(新的在上)。
- 条目 H3 ——
分类 · 文档标题。标题文本即锚点,所以每条都能单独发给别人(#新增--站点导览)。 - 元信息三行 —— 文件(点进去看现行内容)、版本与标签(判断这条是否适用于你手上的版本)、对比(跳到那次提交看真实 diff)。
- 分类 —— 决定这条该不该看,判定规则见下。
分类怎么判定
机器能判断「文件是新增还是修改」,判断不了「这次修改是不是纠正了旧结论」。所以分两类来源:
| 分类 | 来源 | 判定 |
|---|---|---|
| 新增 | 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 # 只回溯某个时间点之后的提交
三条硬规则:
- 年度文件不要手改。生成器会整篇重写 frontmatter 与正文,手工修改在下一次生成时消失。
- 新年度自动开文件。跨年后第一次提交会自动产生
2027.md,sidebar_position按年份倒序自动算,不需要改任何配置。 - 对比链接按需生成。
site.config.js的repo.owner/repo.name为空时不输出任何 compare 链接——宁可没有,也不给死链。填好这两项后重新生成即可补上。
与订阅的关系
变更日志是邮件汇总的唯一输入源:订阅脚本读年度文件里当天的条目,按 tags 分组投递。所以条目的三行元信息不是装饰——缺文件或缺标签的条目会在汇总里降级成一行标题,信息量立刻变少。想让订阅者一眼看懂,就写清分类与标题。
与版本化的关系
历史版本(如 5.8)的页面是快照,不会随主干的修订变化;更新日志只记录主干。两 者冲突时:先看你读的是哪个版本的页面,再看那条记录对应的版本字段。