我请社区的开源从业者分享了他们关于编写有用的 Git 提交信息的建议。

最近，当需要更新时，我一直在密切关注从产品和服务获得的变更日志。以下是一些示例：

  • 修复了一些错误。
  • 进行了一些可访问性改进。
  • 我们已经进行了改进，并修复了错误，以实现更顺畅地运行。

当我想到我还是一名初级开发人员写的一些首次提交信息时，我不得不沮丧地垂下头：

  • 用鼠标点了一下，现在一切似乎都正常了。
  • 执行了程序员 X 告诉我的操作，现在横幅是蓝色的。

这可真令人沮丧！我向我们的贡献者们提出了以下问题：

  • 什么是好的 Git 提交信息？
  • 什么是坏的 Git 提交信息？
  • 你认为一个项目应该有哪些关于提交信息所写内容的规则？

以下是他们的答案：

易阅读的文笔是关键

与你写任何东西一样，你应该考虑谁会阅读它。然后相应地调整信息的数量和深度。

提高你的自然语言和写作技能对于软件开发的职业生涯顺利发展至关重要。重要的不仅仅是代码。

—— Camilla Conte

具有描述性，不要假设

我在 OpenStack 社区中花了很多时间合作，与我在像“野外”的其他随意的项目中看到的相比，它的代码审查者有一些相当严格的标准。

我花在撰写一条可靠的提交信息的时间，往往要比编写实际的代码实现或修复程序的时间长得多。有时，提交信息可能会比它们解释的代码变化长很多倍。

总结一些贡献者指导：

  • 描述为什么要做出改变，而不仅仅是改变了什么
  • 第一个提交行是最重要的（就像电子邮件的主题行）
  • 不要假设审查者了解你正在修复的原始问题
  • 不要假设审查者可以访问外部 Web 服务或网站（总结缺陷报告和其他相关讨论）
  • 不要假设代码是不言自明的和自我说明的（尽管没有必要重复你在代码注释中也提出的观点）
  • 不要只包含与更改的早期修订相关的信息（我们希望贡献者将修订压扁在一起，并相应地编辑其提交信息）。

《OpenStack 贡献者指南》中有一个关于该主题的 简短章节。

—— Jeremy Stanley

未来的你会感谢自己

我非常同意 Jeremy 的观点。+1000。

Jeremy 说：“描述为什么要做出改变，而不仅仅是改变了什么。”

想象一下，你是旁观者，在遥远的未来试图理解这个提交。

正如老话所说，设身处地为他人着想。

—— Leigh Morresi

使用 bug ID

我建议在提交信息的开头添加 bug ID，这样在以后使用 grep 命令 跟踪提交信息时就会更方便。

例如：

$ git commit -m "BZ#19xxxxx

要写出深思熟虑的提交，请考虑以下事项：

  • 我为什么要做这些更改？
  • 我的更改产生了什么影响？
  • 为什么有更改的必要？
  • 更改的依据是什么？

—— Agil Antony

讲述整个故事

我喜欢想象每个提交信息都有一个隐藏的前缀，上面写着 “By applying this（通过应用这个）”。

一个好的提交信息包括将要发生的事情以及原因。仅仅有工单作参考是不够的，因为这分散了信息；Git 是去中心化的。作为一名软件开发人员，我想知道为什么当前要考虑做出更改。正在解决的具体问题是什么？考虑（并放弃）了哪些替代解决方案？在创建变更集的过程中发现了哪些影响当前内容的意外情况？

缩短提交信息没有什么好处。你未来的自己和未来的同事会感激你深入地解释了问题，以及为什么这个变更集是解决方案。认真学习和利用那些内容丰富的“烹饪”博客。然而，在此，仅仅是把生活经验替换成了项目的问题罢了（LCTT 译注：意思是要认真学习和模仿优秀、详细的提交信息）。

—— Lisa Seelye

但不要过于冗长

一个好的 Git 提交信息包含有关所做操作的信息，而不要包含其他信息。例如，如果你需要更新 .gitignore，只需写 “更新了 .gitignore” 即可。人们可以自行深入到提交本身中了解更多细节。它不需要冗长。

糟糕的提交信息类似于“哦，糟糕”或“试试这个”。当然，我也曾经犯过这样的错误，但这对于任何需要一目了然地查看提交信息的人来说都没有任何帮助。

提交信息的规则非常主观。他们可能因领导和团队而异。但至少要提供一些有关提交的上下文信息。特别是如果它是一个大的更改。没有人有时间浏览 1000 多个具有大量更改历史的文件。

—— Miriam Goldman

使用现在时

我喜欢项目经理风格的提交信息，用现在时而不是将来时的术语编写（例如，“添加” 而不是“已添加”）。然而，这通常只有在频繁提交时才有可能。当你面临最后期限时，你能记住的只有“我是如何做的”而已。然而，写得好的提交不仅有助于合作者，而且有助于提交者回忆历史。

—— Chris Okpada

不要依赖链接

我想提醒同事们的一件事是，你不仅仅是向给你的提交作批准的人解释。你还要向未来的开发人员和用户解释，他们在使用 bisect 或 blame 定位问题时发现了这个提交，并试图了解其相关性。

如果提供的唯一的上下文是指向某个外部系统的链接，并且在未来很长一段时间内，它所链接的系统不再使用，或者该用户无法访问，那么你的提交信息将变得无用，可能还不如空白。

我经常去挖掘一些开源项目的 Git 历史，发现有些提交信息无非就是一个 Bug ID，或者是某个公司内部的和专用的缺陷跟踪器的链接。

不要依赖链接！

—— Jeremy Stanley

清晰简洁的变更日志

作为一名发布沟通经理，我会经常阅读整个发布版块。我还会与开发人员会面，讨论任何尚未明确的领域。然后我提前测试了版本。之后，我将通过寻找变更日志和相应的修订或新内容来撰写发布文章。

变更日志是开发人员的个人提醒，但也有相应的提议和工单。你应该适当地将产品名称大写，使用拼写检查器，与标点符号和句子结构保持一致。首席开发人员也应该校对这些。你的客户，即开发人员，正在阅读这些内容。在运行更新之前，他们应该了解哪些信息能更好地为客户服务？

—— Courtney Robertson

具体一点

作为一个经常性的发布经理，我喜欢带有组件名称的提交的信息，以及对更改内容的简要描述。在我们忘记了你聪明的分支名称之后，还可以参考一下这项工作的请求来自何处，这有助于将修复程序联系在一起。

  • “修复致命错误”并不是理想的提交。
  • “ISS-304: 修复具有合作伙伴角色的用户在登录访问控制功能中的致命错误”更好。
  • “ISS-304: 登录访问控制：修复 getPartnerId() 的致命错误”也更好。

我可以查看 Git 提交、分支、合并提交之间的整个关系，并检查更改的各个行和文件。但我在发布过程中没有这样的时间。我希望能够在项目管理工具回溯这项工作的源头，了解哪些组件正在被更改，以及以何种方式进行更改。

—— Ryan Price

让它成为一种习惯

我最喜欢犯的错误是“在我切换分支之前提交”，因为我必须处理其他更紧急的事情。有时候，我需要把我目前的工作提交给一个完全不同的项目。我的经理的策略是让我们像平时一样工作。但当我们变基时，他希望我们在有意义的地方压扁提交，并编写更好的信息。我不能说我们总是这样做，但他的方法确实有道理。

我也有很多“这个坏了，不知道为什么”类型的信息（哈哈），我尝试了一些东西，但想在尝试其他东西之前提交该尝试，以防方法 A 比方法 B 更接近解决问题。我已经写了 10 多年了。

—— RachieVee

你的提交信息建议或提示是什么？让我们在评论中知道。

via: https://opensource.com/article/22/12/git-commit-message

作者：AmyJune Hineline 选题：lkxed 译者：ZhangZhanhaoxiang 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出

添加新评论