My-Notes

002.commit message 规范

5分钟阅读

核心教义

commit message 应该清晰明了，说明本次提交的目的

git commit 两种方式

  1. git commit -m "message"：一行 commit message
  2. git commit：跳出文本编辑器，可以写多行

commit message 的作用

  1. 提供更多的历史信息，方便快速浏览
# 显示上次发布后的变动，每个 commit 占据一行
# 只看行首，就知道某次 commit 的目的
git log <last tag> HEAD --pretty=format:%s
  1. 可以过滤某些 commit（比如文档改动），便于快速查找信息
# 仅显示本次发布新增加的功能
git log <last release> HEAD --grep feature
  1. 可以直接从 commit 生成 Change log

commit message 的格式

如 Angular 规范

commit message 包括三个部分：Header、Body 和 Footer

<type>(<scope>): <subject>
# 空一行 #
<body>
# 空一行 #
<footer>
  • Header 是必需的，Body 和 Footer 可以省略
  • 不管是哪一个部分，任何一行都不得超过 72 个字符（或 100 个字符）。这是为了避免自动换行影响美观

Header 只有一行，包括三个字段：type（类型）、scope（范围）和 subject（主题）

  • type：必需，用于说明 commit 的类别
    • feat：新功能
    • fix：修补 BUG
    • refactor：重构
    • test：增加测试
    • docs：文档
    • style：代码格式，不影响代码运行的变动
    • chore：杂活、零工，如：构建过程或辅助工具的变动
  • scope：可选，用于说明 commit 影响的范围，比如数据层、控制层、视图层等，视项目不同而不同
  • subject：必需，是 commit 目的的简短描述，一般不超过 50 个字符
    • 以动词开头，使用第一人称现在时，比如 change，而不是 changed 或 changes
    • 第一个字母小写
    • 结尾不加句号（.）

Body

是对本次 commit 的详细描述，可以分成多行

范例：

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

注意：

  • 使用第一人称现在时，比如使用 change 而不是 changed 或 changes
  • 应该说明代码变动的动机，以及与以前行为的对比

只用于两种情况：

  1. 不兼容变动：以 BREAKING CHANGE 开头，后面是对变动的描述、以及变动理由和迁移方法
BREAKING CHANGE: isolate scope bindings definition has changed.
 
To migrate the code follow the example below:
 
Before:
 
scope: {
  myAttr: 'attribute',
}
 
After:
 
scope: {
  myAttr: '@',
}
 
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
  1. 关闭 Issue：如果当前 commit 针对某个 issue，那么可以在 Footer 部分关闭这个 issue
Closes #234
 
# 关闭多个Issue
Closes #123, #245, #992

特殊情况：Revert

当前 commit 用于撤销以前的 commit

  • Header：必须以 revert: 开头，后面跟着被撤销 Commit 的 Header
  • Body：必须写成 This reverts commit <hash>.，其中的 hash 是被撤销 commit 的 SHA 标识符
revert: feat(pencil): add 'graphiteWidth' option
 
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

其他

自动化工具

commit 规范检查

生成 Change log

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

生成的文档包括三个部分：

  • New features
  • Bug fixes
  • Breaking changes

每个部分都会罗列相关的 commit ，并且有指向这些 commit 的链接

当然，生成的文档允许手动修改，所以发布前，还可以添加其他内容

生成 Change log 的工具：conventional-changelog

npm install -g conventional-changelog
 
cd my-project
 
# 不会覆盖以前的 Change log，只会在 CHANGELOG.md 的头部加上自从上次发布以来的变动
conventional-changelog -p angular -i CHANGELOG.md -w
 
# 生成所有发布的 Change log
conventional-changelog -p angular -i CHANGELOG.md -w -r 0

关系图谱