1. My favourite Git commit (2019) (dhwthompson.com)
文章《我最喜欢的Git提交》通过分析一个示范性的Git提交信息,阐述了高质量提交信息的重要性和价值。作者以在政府数字服务署(GDS)工作期间,开发者丹·卡利提交的一个提交(题为“Convert template to US-ASCII to fix error”)为例,详细说明了其出色之处。
该提交信息的优点包括:
- 解释变更原因:不仅说明了“做了什么”,更详细阐述了“为什么”要变更。具体描述了遇到的测试错误(
ArgumentError: invalid byte sequence in US-ASCII)及其触发条件,明确了问题根源。 - 便于搜索:包含了具体的错误信息文本,使得其他遇到相同问题的人可以通过代码仓库搜索(如
git log --grep)快速找到历史解决方案。 - 讲述完整故事:详细记录了问题的发现、调查过程(如逐步排查、使用特定命令)以及最终的解决方法,为代码库的演变留下了完整上下文。
- 传播知识与提升团队能力:在信息中记录了调查时使用的具体命令(如结合
find的-exec参数、file --mime、iconv工具等),这为代码审查者和后来查阅者提供了实用的工具使用技巧,有助于团队整体知识提升。 - 体现人文关怀与建立信任:结尾处加入了个人感受(“一小时的光阴一去不返”),增加了人情味,提醒每个变更背后都是一个在当时条件下做出最佳决策的人,有助于构建团队间的理解与信任。
作者认为,尽管这是一个详尽程度的极端例子,但它完美示范了如何通过提交信息提供变更背景、帮助他人学习并丰富团队对代码库的共同理解。文章最后推荐了两篇相关资源供进一步阅读。