以主语开头的提交信息
关于“以主题开头”与传统“以动词开头”的提交信息之争,反映了不同团队对版本控制历史的使用方式有多大差异。有些工程师会扫描日志,希望简洁主题能突出受影响的组件或行为;另一些人则很少回看提交,认为严格格式相较于 diff、PR 和工单系统只是低回报的过度纠结。这场讨论也引出了更深层的问题:提交信息究竟应主要服务于人还是工具,“为什么”应该有多少留在 Git 里、多少放到工单系统中,以及诸如 squash merge、结对编程、无 PR 等工作流选择,如何塑造人们对“好提交信息”的定义。
提交历史被使用的频率
- 经验差异很大。有些人说在多年的工作里几乎从不回看旧的提交信息;另一些人则表示每周甚至每天都会使用历史记录或 blame。
- 常见用途包括:调试(“为什么这段代码会这样?”)、追踪行为何时发生变化、使用 bisect 排查回归,以及理解某些行/文件的影响。
- 也有人认为,提交信息通常比 diff 提供不了更多内容,而且质量往往不高(“wip”“update”),这让人不愿依赖它们。
好的提交信息应包含什么
- 很多人希望提交信息能记录“为什么”和高层次的“是什么”,而让 diff 提供更细节的“怎么做”。
- 简短、便于扫描的主题行加可选的详细正文,是广受欢迎的一种模式。
- 有些人认为提交信息主要是为了自己中间阶段的工作;另一些人则把它们看作长期共享文档和变更日志来源。
- 团队内部的一致性,常被认为比任何特定风格都更重要。
以主题开头 vs 以动词开头的风格
- 支持以主题开头的人认为:把最可变/最重要的部分(受影响的主体/组件)放在前面,能提升扫描效率,这与列表设计和眼动研究的见解类似。
- 反对者则质疑其可读性和所谓的心理学依据,认为动词/动作才是关键(“变了什么”),而且这些例子过于模糊。
- 还有人更喜欢组件前缀格式或 Conventional Commits(
type(scope): summary),因为它们能对变更分类并支持工具化。
提交信息 vs 工单和其他工件
- 许多人强调要包含工单 ID,以便链接到更丰富的业务和讨论上下文;另一些人则不喜欢把 ID 放在标题里,更倾向于放在正文或 trailer 中。
- 也有人警告,工单系统和 URL 可能会变化或消失,使得仅靠提交中的 ID 或链接很脆弱;他们主张提交说明应当自包含。
- 有一个团队描述了一种更广泛的方法:不使用拉取请求,大量结对/群体协作,把文本文件工作和设备日志都放进 git,而提交信息主要作为简洁的、以主题开头的索引。
元话题:价值与过度纠结
- 有些人认为,和产品问题相比,围绕提交风格的争论属于低回报的过度纠结。
- 另一些人则认为,糟糕的信息会造成长期显著的时间损失,而在这里保持适度纪律是值得的。