Git Commit - Angular Convention

使用 Git 的开发者会使用 git commit 进行代码提交，也会使用 -m 提交commit message。对于一些个人开发者，也许他们会觉得「这是我个人的项目，不用太在意git commit message 的格式或者规范」。

但是对于一个团队或者在开源项目上工作的话，对于 commit message 的质量就会有比较高的要求了。一个好的 Git commit message 是向项目的其他参与者进行提交信息说明的十分重要的途径，对于开发这个人而言也在未来回顾提交信息的时候十分有意义。

有时候我们在旧项目上使用 git log 的时候会发现一堆杂乱的 commit messages。很难读懂当时提交这条 commit 的原因，增加或者修改了哪些内容。所以，一个「好」的 commit message 的重要性在于：

  • 一些项目需要严谨的开发过程，以及清楚的可追溯性，相关的责任人。 当这些项目出现问题时，重要的是要知道确切的原因：哪些代码更改不正确，哪些用户会受此问题影响，为什么当时修改了代码等等。
  • 好的代码值得被「认真」地分享。开发者应该不希望自己辛苦写了一个礼拜的代码提交为「add some new features」。我觉得这是对于开发者自己劳动成果的一种不尊重，至少需要体现出解决了哪些问题，哪里比较「酷」。

所以为了其他人，也为了自己，请认真对待 commit messages 🙂

参考下面的 commit (来自网络)：

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)147709f Tweaks to package-info.java files22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils7f96f57 polishing

每次提交的内容从长度到格式都不同，写法像是意识流（非褒义）。在 github 上很多项目都是类似的提交格式，但是也有比较清晰准确的 commit messages，比如 Linux kernel，读者可以参考。

开发者可以自己制定一套 commit 的格式，也可以使用流行的一些格式。这里想要分享的是我个人和团队在使用的一种 commit convention: Angular。https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelinesgithub.com

概述

Angular 规定 commit message 的结构如下：

[optional scope]: [optional body][optional footer(s)]

header + body(可选) + footer(可选)

header

header 包含三部分：type + scope + subject。比如，

feat(lang): add polish language

（1）type

  • feat：新功能（feature）
  • fix：修补bug
  • docs：文档（documentation）
  • style： 格式（不影响代码运行的变动）
  • refactor：重构（即不是新增功能，也不是修改bug的代码变动）
  • test：增加测试
  • chore：构建过程或辅助工具的变动

在 type 后面增加“！”代表重大的代码更改。

（2）scope

用于说明 commit 影响的范围，比如数据层、控制层、或者项目名称等等。

（3）subject

commit 的简短描述，不超过50个字符。

  • 以动词开头，使用第一人称现在时，比如change，而不是changed或changes
  • 第一个字母小写
  • 结尾不加句号（.）

body (非必须)

body 是详细描述的信息，例如：

More detailed explanatory text, if necessary.  Wrap it to about 72 characters or so. Further paragraphs come after blank lines.- Bullet points are okay, too- Use a hanging indent

footer (非必须)

（1）不兼容变动

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

（2）关闭 Issue

如果当前 commit 针对某个issue，那么可以在 Footer 部分关闭这个 issue 。

Closes #234

示例

Commit message with description and breaking change footer

feat: allow provided config object to extend other configsBREAKING CHANGE: `extends` key in config file is now used for extending other config files

Commit message with ! to draw attention to breaking change

refactor!: drop support for Node 6

Commit message with both ! and BREAKING CHANGE footer

refactor!: drop support for Node 6BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

Commit message with no body

docs: correct spelling of CHANGELOG

Commit message with scope

feat(lang): add polish language

Commit message with multi-paragraph body and multiple footers

fix: correct minor typos in codesee the issue for detailson typos fixed.Reviewed-by: ZRefs #133

参考

https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines

https://www.conventionalcommits.org/en/v1.0.0/

https://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html