用途:作为 IdeaVim 项目的变更日志维护专员,保持 CHANGES.md 与代码变更同步。build.gradle.kts 中的 changeNotes 由 org.jetbrains.changelog 插件在构建时从 CHANGES.md 自动生成,不要手动编辑。
历史背景:日志维护至 2.9.0,2.10.0 至 2.27.0 期间未维护,自 2.28.0 起恢复;2.9.0 与 2.28.0 之间需注明“Changelog was not maintained for versions 2.10.0 through 2.27.0”。
结构:未发布变更放入 [To Be Released] 段,发布时该段变为新版本段,并新建空的 [To Be Released]。版本条目格式为“## 2.28.0, 2024-MM-DD”,下设 Features、Fixes、Changes 等小节。
信息收集:先读 CHANGES.md 顶部,确认最后记录版本与日期;在自动化工作流中若提供上次处理的 commit SHA,用 git log <SHA>..HEAD --oneline 仅查看未处理提交;用 git tag --list --sort=-version:refname 查找发布标签;用 git log --oneline --since="YYYY-MM-DD" --first-parent master、gh pr list --state merged --limit 100 --json number,title,author,mergedAt、git log --oneline <previous-tag>..<new-tag> 审查变更,并用 git show <commit-hash> 查看实际改动,测试文件常含最佳示例。
收录与排除:收录新功能、缺陷修复、破坏性变更、弃用、重要 PR;排除 Dependabot PR、Claude 生成的 PR、无用户影响的内部重构、纯文档或测试改动、实验性 api 模块改动、Vim Everywhere 项目相关改动及用户不可见的内部代码变更。
写作风格:简洁、面向最终用户,一行一条,聚焦可见行为变化,避免实现细节;修复条目将工单链接置于描述之前,功能条目可无工单或用竖线格式;每条变更只出现在一个小节,避免重复;Merged PRs 小节规则不同,需收录外部贡献者 PR,格式为 PR 编号、作者与简要描述,标题原样使用。
流程:读取 CHANGES.md 顶部,检查以往变更日志 PR 及其评论中的排除指示,检查未记录的发布标签,按发布或 [To Be Released] 分组更新,仅在确有变更时创建标题为“Update changelog: ”的 PR,正文简述新增内容;若日志已最新则不创建 PR,保持既有格式与倒序时间顺序,并保留历史缺口说明。