最近，我一直在更密切地关注产品和服务在需要更新时提供的变更日志。以下是一些示例
- 修复了一些错误。
- 进行了一些辅助功能改进。
- 我们进行了改进并修复了错误，以获得更顺畅的体验。
当我想起我作为初级开发人员时写的一些最早的提交消息时，我不得不羞愧地低下头
- 随意点击了一下，现在似乎可以工作了。
- 按照程序员 X 告诉我的做了，现在横幅变成蓝色了。
这可能会令人沮丧！我向我们的贡献者社区提出了以下问题
- 是什么造就了一条优秀的 Git 提交消息？
- 是什么造就了一条糟糕的提交消息？
- 您认为一个项目应该对提交消息包含的内容有哪些规则？
以下是他们的回答
优秀的写作是关键
与您写的任何东西一样，您应该考虑谁将阅读它。然后相应地调整信息量和深度。
提高您的自然语言和写作技巧对于软件开发领域的健康职业生涯至关重要。重要的不仅仅是代码。
要有描述性，不要想当然
我花了很多时间在 OpenStack 社区中进行协作，与其他“野外”项目相比，它的代码审查员有一些相当严格的标准。
我经常花比编写实际代码实现或修复更长的时间来撰写可靠的提交消息。有时提交消息的长度最终会比它们解释的差异长很多倍。
总结一下贡献者的指导
- 描述进行更改的原因，而不仅仅是更改的内容
- 第一行提交行是最重要的（就像电子邮件的主题行一样）
- 不要假设审查者理解您正在修复的原始问题
- 不要假设审查者可以访问外部 Web 服务或站点（总结缺陷报告和其他相关讨论）
- 不要假设代码是不言自明的和自文档化的（尽管没有必要重复您在代码注释中也提出的观点）
- 不要包含仅与更改的早期版本相关的信息（我们希望贡献者将修订压缩在一起并相应地编辑其提交消息）。
OpenStack 贡献者指南中有一个关于该主题的简短章节：https://docs.openstack.org/contributors/common/git.html#commit-messages
未来的你将感谢你
我非常同意 Jeremy 的观点。+1000
Jeremy 说，“描述进行更改的原因，而不仅仅是更改的内容。”
想象一下，您是其他人，在遥远的未来，试图弄清楚这个提交。
正如俗话所说，设身处地为他人着想。
使用错误 ID
我建议在提交消息的开头添加错误 ID，以便以后使用 grep 命令更轻松地跟踪提交。
例如
$ git commit -m "BZ#19xxxxx 要提出周到的提交，请考虑以下几点
- 我为什么要做这些更改？
- 我的更改产生了什么影响？
- 为什么需要进行更改？
- 更改是针对什么而言的？
讲述整个故事
我喜欢想象每个提交消息都有一个隐藏的前缀，内容为“通过应用此项”。
好的提交消息准确地包括将要发生的事情以及原因。仅仅拥有工作票证参考是不够的，因为这会分散信息；Git 是去中心化的。作为一名软件开发人员，我想知道为什么要考虑提出的更改。正在解决什么具体问题？考虑（并放弃）了哪些替代解决方案？在创建变更集期间发现了哪些影响当前内容的意外情况？
最短的提交消息没有奖励。您未来的自己和未来的同事会感谢您深入解释问题以及为什么此变更集是答案。利用那些有五段生活故事的烹饪博客。但是，在这里，让问题成为生活故事的主题。
但不要过于冗长
好的 git 提交消息包含有关已完成工作的信息，仅此而已。例如，如果您需要更新 .gitignore，只需说“updated .gitignore”。人们可以深入研究提交本身以获取更多详细信息。它不需要冗长。
糟糕的提交消息类似于“oh crap”或“try this”。诚然，我对此感到内疚，但这无助于任何需要在匆匆一瞥中查看提交的人。
规则非常主观。它们可能因负责人和团队而异。但至少，提供一些关于提交的上下文信息。特别是如果这是一个很大的提交。没有人有时间浏览 1000 多个具有繁重更改历史记录的文件。
使用现在时
我喜欢以项目经理风格编写的提交消息，使用现在时而不是将来时（例如，“add”而不是“added”）。但是，只有在提交频繁的情况下才有可能。当您面临截止日期时，您只能记住那么多“我是怎么做的”。然而，写得好的提交不仅可以帮助协作者，而且还有助于提交者回忆历史。
不要依赖链接
我想提醒同事的一件事是，您不仅是在向将决定是否批准您的提交的人解释，而且还在向未来的开发人员和用户解释，他们已经在二分查找或 blame 操作中找到了此提交，并试图理解其相关性。
如果提供的唯一上下文是指向某些外部系统的链接，并且在遥远的未来，它链接到的系统不再使用或以其他方式变得个人无法访问，则您的提交消息已变得毫无用处，并且可能与空白一样好。
我经常深入研究某些开源项目的 Git 历史记录，并发现提交消息只不过是一个错误 ID 或指向某些公司内部和私有缺陷跟踪器的链接。
不要成为那个项目！
清晰简洁的变更日志
作为发布沟通经理，我经常阅读整个发布板。我还与开发人员会面，讨论任何尚不清楚的领域。然后，我尽早测试了发布版本。之后，我将通过从变更日志和相应的修订或新内容中获取信息来编写发布帖子。
变更日志是开发人员的个人提醒，但也有针对他们的相应问题和工单。您应该正确地将产品名称大写，使用拼写检查器，并在标点符号和句子结构上保持一致。首席开发人员也应该校对这些内容。您的客户，即开发人员，正在阅读这些内容。在运行更新以更好地服务于他们的客户之前，他们应该知道哪些信息？
要具体
作为一名经常发布的发布经理，我喜欢命名提交触及的组件的消息，以及对更改内容的简要描述。还有一个指向此工作请求来源的参考，有助于在我们忘记您聪明的分支名称很久之后将修复联系在一起。
- “fix fatal error”并不理想。
- “ISS-304：修复合作伙伴角色的用户的登录访问控制功能中的致命错误”更好。
with the Partner role" is better. - “ISS-304：登录访问控制：修复 getPartnerId() 中的致命错误”
更好。
我可以查看 Git 提交、分支、合并提交之间的整个关系，并检查已更改的各个行和文件。但是我在发布过程中没有那么多时间。我希望能够联系回项目管理工具中这项工作的来源，了解正在更改哪些组件以及以何种方式更改。
使其成为习惯
我最喜欢的我承认犯过的提交是“在切换分支之前提交”，因为我必须处理其他更紧急的事情。有时，我需要将当前工作提交到完全不同的项目。我经理的策略是让我们像往常一样工作。但是，当我们变基时，他希望我们压缩有意义的提交并编写更好的消息。我不能说我们总是这样做，但他的方法确实有道理。
我也有很多“this is broken don't know why”类型的消息（哈哈），我在其中尝试了一些方法，但想在尝试其他方法之前提交该尝试，以防方法 A 比方法 B 更接近修复问题。编写代码是一团糟。我已经写了 10 多年了。
您坚持哪些提交消息建议或技巧？请在评论中告诉我们。
1 条评论