SuperAPI AI 工具集

changelog-discipline

写作与研究

查看项目

更新于 10-15 20:09

技能介绍

用途:在维护 changelog 的项目中,每次完成代码改动后立即在 [Unreleased] 中补写一条记录;也用于新项目配置 changelog 和准备发布。不用于提交信息、PR 描述和面向用户的发布说明。

核心原则:写给半年后回看的自己;完整性不要求评估重要性,改过代码就留记录,一条记录对应一个完整改动而非单个文件或提交;深度取决于决策——机械性改动只需说明区域并注明行为未变,非显然决策需写明原因、旧状态和已否决方案;“为什么”比“什么”更值钱;changelog 不描述当前状态,只解释为何变化并指向现行来源;已否决的替代方案比被采纳的方案更有价值;记录要即时写,不要拖到发布前。

格式:文件含标题、Keep a Changelog 说明、[Unreleased] 区块(Added / Changed / Fixed)及带日期的版本区块。每个版本有四项摘要:什么(以产品而非代码表述现在有何不同)、哪里(涉及的文件与区域)、为什么(解决什么痛点)、之前(旧行为)。版本内条目以加粗一句话概括,写明改了什么、在哪里,机械改动注明行为未变,非显然决策写原因、旧状态和否决方案。

流程:每次完成代码改动后立即按类别补一条;选择深度;行为变化时从产品角度表述;发布时将 [Unreleased] 转为带日期的版本并写四项摘要。

限制:资料仅给出上述规则、格式与流程,未提供具体安装命令、工具集成方式、平台和收费信息,暂未提供。参考文件为 references/01-antipatterns.md 和 references/02-examples.md。