SuperAPI AI 工具集

writing-commits

编程与开发

查看项目

更新于 11-12 01:16

技能介绍

writing-commits 是一个关于如何写 Git 提交信息的技能,目标读者是几个月后通过 git blame 或 git bisect 看到某一行改动、并追问“为什么是这样”的人。这类读者手里只有 diff,没有当时的对话、issue 讨论串、开发服务器,也没有原作者,因此提交信息是这次改动唯一留存下来的说明,必须独立承载原因。

核心主张是先讲问题。diff 只显示改了什么,从不会显示改之前哪里不对,也不会显示如果回滚会破坏什么。

格式方面:如果仓库已有约定,就遵循它,可通过查看 git log 判断;如果没有约定,使用以下形式——主题行面向对项目一无所知的人,不超过72字符;PROBLEM 说明原先哪里错了,不超过100词,若有简短具体的例子(如代码示例或错误输出)可附上,例子不计入字数;SOLUTION 说明改动如何应对,不超过160词;之后可选 DESIGN DISCUSSION,用于说明结构、被否决的替代方案以及设计依据。正文按72列换行,并用 scripts/commit-width.sh 检查,而不是凭肉眼判断。

提交信息应描述改动本身,而非写作时的环境:省略家庭目录路径、工作树名称、端口、开发服务器 URL、运行 ID,以及任何指向对话的内容(如“按要求”“用户提出”)。应使用持久性的称呼,如“本地开发服务器”而非“:8026”。issue 编号可以出现,这里正是它该在的地方。不要陈述没有被提供的信 息:如果会话从未确定重试次数或请求头名称,信息中就不要写出它们。

文中列出的失败模式包括:复述 diff 而不说明问题所在;残留会话痕迹(路径、端口、运行 ID 或对话引用);只有在场者才看得懂的主题行(如“修一下重试那个”“处理评审意见”);编造改动并未确立的公式、限制或名称;把 PROBLEM/SOLUTION 格式强加于已有自己约定的仓库。