Git Commit Message Style

Git 提交日志编写规范

如何编写优秀的 commit 信息？

基本格式

注意: commit 信息必须使用英文进行编写。

简单的描述下这个commit改变了什么。（不超过 50 个字.若隶属某个模块可以使用模块名+':'的形式）
<若有正文则此处*必须*空一行>

如果有更细致的描述就写在这里。每一行不要超过 72 个字。
这里应该描述为什么要这样做以及是如何

<若正文需要可以选择空行>
正文内容可以使用 ‘-’，‘**’ 等非常通用的标记。但标题中不允许出现。

Resolves: bug 描述的具体地址。元信息可以不遵循 72 字 wrap 的规定
<元信息需要使用空行分离>
See also:
- 若有多个链接则采用多行See also: 的形式进行表达
- 其他 CL 链接或 bug 链接
- 对某些功能或 bug 有影响的链接

关于链接有两点需要注意

1. 应使用可以直接访问到的地址。不可以是一个 bugid 或 CL id 号
2. 链接的访问权限不应该高于此 commit 的访问权限。简单的说就是能看到 commit 的人也需要可以访问到 commit 中的链接 (未解决tower问题前此处不限制tower任务)

基本原则

”基本格式“看起来非常简单。但仅仅达到基本格式的要求依旧写不出好的 commit。但只要我们遵循以下 7 条原则，基本很难 写出差的commit。更详细的参考资料 7条原则

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

第 3，4 条，说的是一个简单的事实：第一行是标题，标题首字母大写（由于使用Angular Commit Message Format，不用遵守第三条，不需要首字母大写），标题不是句子不需要句号。

第 5 条，使用祈使句非常非常重要。简单的说，第一个动词用原型，不要 使用 ing 或 ed 的形式。

第 7 条，重点描述做了什么以及为何要这样做而不是那样做。代码的 diff 会告诉后来者你选择的方式是怎么做的。但代码无法记录做这个 change 时 候的决策。

推荐玩法

遵循 7 条基本原则后的 commit 已经看上去不错了。但还有很多方式可以 让我们更容易更自然的写出优秀的 commit

• 不要使用 git commit -m <msg> 让编辑器来保障你不会犯丢人的错误吧。
• 在 commit 的编辑器中开启拼写检查。伙计，全世界都盯着在，像你这么厉害的人不想被人翻老底吧。
• 使用 git add -p 或者 magit 来方便快捷的对一个文件的部分区域 进行提交。绝大多时候写不出第一行就是因为一次提交过多了。让你的 commit 更加原子性吧。
• 使用 Angular Commit Message Format， 可以方便使用clog工具生成CHANGELOG.md. 参考: Generate CHNAGELOG.md with clog
• 参考动词 (可参考 jenkins的changelog)
  • Fix
  • Release
  • Change
  • Remove
  • Add
  • Implement
  • Enable
  • Improve
  • Refactor
  • Update
  • Make
  • Reduce

参考文档

• https://github.com/erlang/otp/wiki/Writing-good-commit-messages
• http://git-scm.com/book/ch5-2.html
• http://www.freshconsulting.com/atomic-commits/
• https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
• https://news.ycombinator.com/item?id=10212582