Git Commit Message 提交信息规范指南

（1）不兼容变动

如果当前代码与上一个版本不兼容，则 Footer 部分以 BREAKING CHANGE 开头，后面是对变动的描述、以及变动理由和迁移方法。

（2）关闭 Issue

如果当前 commit 修复某个 issue，那么可以在 Footer 部分修复这个 issue。

也可以一次关闭多个 issue。

1.4 Revert

还有一种特殊情况，如果当前 commit 用于撤销以前的 commit，则必须以 revert: 开头，后面跟着被撤销 Commit 的 Header。

Body 部分的格式是固定的，必须写成 This reverts commit <hash>.，其中的 hash 是被撤销 commit 的 SHA 标识符。

如果当前 commit 与被撤销的 commit，在同一个发布（release）里面，那么它们都不会出现在 Change log 里面。如果两者在不同的发布，那么当前 commit，会出现在 Change log 的 Reverts 小标题下面。

2. Commit Message 相关工具

2.1 npm 安装

2.2 Commit Message 编写工具

Commitizen 是一个撰写合格 commit message 的工具。

安装命令如下。

然后，在项目目录里，运行下面的命令，使其支持 Angular 的 Commit message 格式。

以后，凡是用到 git commit 命令，一律改为使用 git cz。这时，就会出现选项，用来生成符合格式的 Commit message。

2.3 Commit Message 校验工具

validate-commit-msg 用于检查 Node 项目的 Commit message 是否符合格式。

2.4 Commit Message 转换为 Changelog 工具

如果你的所有 Commit 都符合 Angular 格式，那么发布新版本时，Change log 就可以用脚本自动生成。

生成的文档包括以下三个部分。

New featuresBug fixesBreaking changes.

每个部分都会罗列相关的 commit，并且有指向这些 commit 的链接。当然，生成的文档允许手动修改，所以发布前，你还可以添加其他内容。

conventional-changelog 就是生成 Change log 的工具，运行下面的命令即可。

上面命令不会覆盖以前的 Change log，只会在 CHANGELOG.md 的头部加上自从上次发布以来的变动。

如果你想生成所有发布的 Change log，要改为运行下面的命令。

为了方便使用，可以将其写入 package.json 的 scripts 字段。

以后，直接运行下面的命令即可。

3. Commit Message 指导原则

3.1 结构变化

创建良好提交的基本规则是确保每个提交只有一个'逻辑更改'。这是一条重要规则的原因有很多：

• 更改的代码量越少，复查和识别潜在缺陷的速度就越快越容易。
• 如果以后发现更改存在缺陷，则可能有必要还原损坏的提交。如果没有其他不相关的代码更改与原始提交纠缠在一起，则这样做更容易。
• 当使用 Git 的 bisect 功能对问题进行故障排除时，定义明确的小变化将有助于准确地找出引入代码问题的位置。
• 当使用 Git 注释/责备浏览历史记录时，定义明确的微小更改也有助于准确隔离代码的来源和原因。

3.2 创建提交时应避免的事项

考虑到这一点，有一些经常遇到的不好的事情要避免的例子：

• 将空白更改与功能代码更改混合在一起。

空格更改将掩盖重要的功能更改，从而使审阅者更难正确地确定更改是否正确。解决方案：创建 2 个提交，一个提交带有空白更改，一个带有功能更改。通常，将首先进行空白更改，但这并不是硬性规定。

• 混合两个不相关的功能更改。

同样，如果将两个不相关的更改混合在一起，那么审阅者将更难发现缺陷。如果以后有必要还原损坏的提交，则这两个无关的更改将需要进行处理，从而进一步增加了错误创建的风险。

• 在一次大型提交中发送大型新功能。

很可能只有当所有新功能都存在时，新功能的代码才有用。但是，这并不意味着应在单个提交中提供整个功能。新功能通常需要重构现有代码。非常需要在与实现新功能的提交分开的提交中进行任何重构。这可以帮助审阅者和测试套件验证重构是否具有无意的功能更改。即使是新编写的代码，也经常可以分为多个部分，可以独立进行检查。例如，添加新的内部 API/类的更改可以在独立的提交中进行。再次，这使得代码审查更加容易。如果还没有立即准备好合并新功能，则它还允许其他开发人员精挑细选工作的一小部分。应该在与实际内部实现分开的提交中添加新的公共 HTTP API 或 RPC 接口。这将鼓励作者和审阅者考虑通用的 API/RPC 设计，而不是简单地选择一种对其当前选择的内部实现更容易的设计。

遵循的基本规则是：

拆分代码更改优于合并大提交。

3.3 提交消息中的信息

与更改内容一样重要的是描述更改的提交消息的内容。编写提交消息时，需要记住一些重要的事情：

• 不要以为审阅者理解最初的问题是什么。

在阅读错误报告时，经过多次来回评论后，问题的根本原因通常像泥泞一样清晰。提交消息应清楚说明原始问题是什么。该错误仅是有关/如何/发现问题的有趣历史背景。无需阅读错误凭单，就应该有可能检查提议的补丁的正确性。

• 不要以为审阅者可以访问外部 Web 服务/站点。

在有人在火车、飞机、大巴、海滩或酒吧等环境中排查问题并浏览 Git 历史记录的 6 个月时间内，无法保证他们将有权访问在线错误跟踪器或在线蓝图文档。分布式 SCM 的一大进步是，您不再需要'在线'就可以访问有关代码存储库的所有信息。提交消息应完全独立，以保持该优势。

• 不要认为代码是不言而喻的/自我证明的。

对于一个人来说，不言而喻的东西，对于另一个人来说，似乎是泥泞。始终记录最初的问题是什么以及如何解决，除了最明显的错别字或仅提交空白以外的任何更改。

• 描述为什么要进行更改。

一个常见的错误是仅记录代码的编写方式，而没有描述开发人员选择这样做的原因。一定要描述整体代码结构，尤其是对于较大的更改，但更重要的是描述更改背后的意图/动机。

• 阅读提交消息，看看它是否暗示改进的代码结构。

通常，在描述大型提交消息时，很明显，实际上应该将提交分为两部分或更多部分。不要害怕返回并重新设置更改基础，以将其拆分为单独的提交。

• 确保有足够的信息来决定是否进行审查。

当 Gerrit 发送电子邮件警报以提交新的补丁程序时，其中包含的信息很少，主要是提交消息和文件列表更改。鉴于补丁数量众多，期望所有审阅者都仔细检查补丁是不合理的。因此，提交消息必须包含足够的信息，以提醒潜在的审阅者以下事实：这是他们需要查看的补丁。

• 第一行提交是最重要的。

在 Git 提交中，提交消息的第一行具有特殊的意义。它用作电子邮件主题行，git 注释消息，gitk 查看器注释，合并提交消息以及更多空间有限的地方。除了总结更改本身之外，还应注意详细说明代码的哪些部分受到影响。例如，如果它影响 libvirt 驱动程序，请在第一行中提及'libvirt'。

• 描述当前代码的任何限制。

如果要更改的代码仍具有未来的改进范围，或者存在任何已知的限制，请在提交消息中提及这些限制。这向审阅者表明，已经考虑了更广泛的情况，并且在短期目标与长期愿望之间进行了权衡。

• 不包括特定于补丁集的注释。

换句话说，如果您要对更改进行重新设置，请不要在提交消息中添加'补丁集 2：重新设置'。更改合并后，这将不再重要。但是，请务必在 Gerrit 中记录一下，以作为您所做更改的评论。它可以帮助审阅者了解补丁集之间的变化。这也适用于注释，例如'添加的单元测试'，'修复的本地化问题'，或任何其他不影响提交总体意图的补丁集更改，例如补丁集更改。

要遵循的主要规则是：

提交消息必须包含完全理解和检查补丁程序的正确性所需的所有信息。拆分代码更改优于合并大提交。