六年前，David Thompson 写了一篇名为“My favourite Git commit”的热门博客文章，庆祝其同事写的一个详细且富有奇思妙想的提交消息。当时作者很喜欢这篇文章，并将其作为好提交消息的范例发送给了几位队友。

最近作者重新审视这篇文章，准备创建自己的编写有用提交消息指南，却惊讶地发现无法说明为何这篇文章是好软件工程的范例。

Thompson 最喜欢的提交

提交消息为：

Convert template to US-ASCII to fix error 🔗︎

引入了一些测试到特性分支以匹配/etc/nginx/router_routes.conf的内容，在bundle exec rake spec或bundle exec rspec modules/router/spec运行时正常，但在bundle exec rake运行时会因ArgumentError: invalid byte sequence in US-ASCII而失败。最终发现删除.with_content(//)匹配器可消除错误，且该文件是代码库中唯一识别编码为utf-8的文件，转换为US-ASCII后错误消失，测试通过。

该提交消息详细描述了一个单字符空白变化的调试过程，但存在一些问题：

• 重要信息后置：前半部分冗长，重要的更改信息在结尾才出现，不符合提交消息应先呈现重要信息的原则。
• 未解释问题：虽提到文件编码问题，但未解释为何会出现utf-8字符，需通过查看源代码才能知晓。
• 未链接代码：引用外部代码时未命名分支或指定提交哈希，读者无法重现开发者的发现。

作者的改写

提出了对 Thompson 最喜欢的 Git 提交的修订：

Convert routes.conf.erb template to US-ASCII 🔗︎

routes.conf.erb有一个意外引入的 stray UTF-8 字符（在5a8607中），rake期望 US-ASCII 格式，该字符导致rake中的测试失败，此更改用等效的 US-ASCII 字符替换 UTF-8 字符。

The stray UTF-8 character 🔗︎

问题在modules/router/templates/routes.conf.erb的第 463 行，0xC2 0xA0不是有效的 US-ASCII 字节序列，是UTF-8 非断行空格字符，任何期望 US-ASCII 编码的工具都会失败。

How I discovered this 🔗︎

在特性分支引入测试以匹配/etc/nginx/router_routes.conf（见abcd123），在bundle exec rake spec或bundle exec rspec modules/router/spec运行正常，但bundle exec rake时失败，删除.with_content(//)匹配器可消除错误，通过rake -E 'require "puppet"' spec可重现错误，该文件是代码库中唯一识别为utf-8的文件，转换后file识别为us-ascii，测试通过。

作者进行了多项修改，如添加高级摘要、明确 UTF-8 字符及来源、将部分内容移至“如何发现”部分等，同时简化了一些内容。

定义自己原则的价值

重新审视 Thompson 的文章让作者意识到为自己定义软件工程原则的价值，通过解释自己对不同软件工程实践的观点，能让自己成为更好的开发者，如代码审查、发送代码审查、编写单元测试等。

进一步阅读

“How to Write Useful Commit Messages”，作者更详细的关于好提交消息的解释。