SuperAPI AI 工具集

writing-changelogs

写作与研究

查看项目

更新于 10-16 08:01

技能介绍

用途:在交付有意义的变更(功能、较大修复、移除)后编写更新日志条目、发布说明,或总结“本次交付了什么”。不要用于琐碎改动(约三个改动文件或三次提交),也绝不可重写或删除已有条目。

主要能力与规则:一条已交付变更对应一条条目,最新在前,使用 ISO 日期,存在版本时按版本分组。文件若使用标准分类,则采用 Added/Changed/Deprecated/Fixed/Removed/Security;Deprecated 条目要写明移除日期与替代方案。破坏性变更置于分类之前、条目开头,须写明所需的迁移操作,有迁移指南时给出链接。侧重用户可见影响而非实现细节;用现在时、主动语态,避免读者不懂的术语;合并相关变更,不重复已有条目;记录移除,而不只是新增。

条目结构:以粗体开头说明结果,再写根因,最后是修复,名称原样内联。固定类条目解释失败模式而非差异,粗体开头承载用户影响,便于读者快速甄别。

发布说明是同一批事实面向受众的裁剪版:改了什么、影响谁、该做什么。更新日志面向工程师,发布说明面向系统用户,两者来源相同且不得互相矛盾。

诚实性约定:三种条目让更新日志可被引用——本次变更暴露但未修复的已知问题、仍待处理的延后事项、按类别说明的有意省略,以免同一省略被反复争论或误认为疏漏。未经确切的完成与核对,不得标记为已实现、已部署或已验证,需区分已实现(在仓库中)、已部署(线上)与外部验证。

交接/完成总结按序覆盖:这项工作的缘由、交付了什么、评审应关注何处(评审者需先理解决策)、验证状态(确切命令与结果,不用空泛的勾)、诚实的注意事项与自己的错误、残余风险与不应做的事、当前状态与尚欠事项(已合并未推送、迁移、有顺序的步骤及顺序错误的后果)。

限制:需技术写作技能作为必备背景;不适用于琐碎改动;不得重写或删除历史条目。