这是关于在 Git 或其他版本控制系统中编写良好提交消息的个人指南，主要内容如下：

• 引言：已有很多提交消息指南，但很多聚焦于琐碎细节，此指南重点在信息，而非排版，作者认为自己的提交消息写得不错，至少能进前 5%。

• 应包含哪些信息：

  • 读者及目的：用户、bug 调查者、代码审查者、同项目其他开发者、浏览源代码历史的人及自己等可能会读提交消息，他们想了解变更对程序行为的影响、副作用、变更原因等。
  • 具体信息：描述对用户可见行为的预期变更、提及已知的副作用、解释变更原因、指出补丁的有趣部分、描述补丁结构、说明补丁未做之事、提供外部上下文链接等。并非每次都需包含所有信息，可根据具体情况考虑。

• 在提交消息中还是其他地方：

  • 优先使用提交消息：提交补丁时，应将说服开发者接受补丁的解释放入提交消息，而非覆盖信，若补丁有嵌入提交消息，也应尽量在其中多解释，若有多个补丁，覆盖信可提供整体概述。
  • 区分提交消息和代码注释：提交消息应描述 API 的变更，代码注释应描述代码的当前状态。
  • 调整补丁以简化提交消息：可将大而复杂的补丁拆分为多个小补丁，使提交消息更简洁，例如将 boring 部分和 interesting 部分分开提交。

• 写作风格：

  • 明确前后状态：在提交消息中要清楚标记描述的是旧代码还是新代码，可添加额外单词来表明上下文，避免仅用语法时态导致歧义。
  • 金字塔写作：采用金字塔写作原则，将重要信息放在顶部，按信息对读者的重要性递减排列，避免冗长啰嗦，让读者能快速找到关键信息。
  • Git 主题行：Git 要求提交以单独的短主题行开头，提供足够信息以区分提交，可包含票号、模块名或功能关键词等，避免主题行过于通用，若有多种信息，可权衡其重要性决定放入主题行的内容。
  • 换行和标记：提交消息一般为纯文本，要考虑标准工具的显示限制，合理换行，使用 Markdown 标记要谨慎，确保文本在无 Markdown 渲染器的情况下也可读，以适应不同的查看工具和分布式版本控制环境。
• 不必每次都做所有事情：不必要求提交消息达到完美标准，可逐步改进，例如挑选一个未做的事项开始改进，或设定时间框进行改进，作为代码审查者也可关注并改进提交消息。
• 临时笔记提交消息例外：在初始开发时，可写更简洁的临时提交消息，专注于让代码工作，等代码稳定后再整理为正式的提交消息，可参考 XKCD #1296“Git Commit”。
• 脚注：包含一些对正文的补充说明和个人观点等。