暂无图片
暂无图片
暂无图片
暂无图片
暂无图片

Git commit message规范制定与实践

giscafer 2019-04-12
712

介绍

  • 制定 git message提交规范

  • 工具限制行为


如果要执行规范,工具是一定要有的。通过工具来限制开发人员的习惯的,一方面保证所有人参与项目都强制按照统一的规范来操作,另一方面是如果你没有工具去强制执行规范,不是每个人都会自觉遵守,行为规范没法统一的话,规范也就没有多少存在的意义了。

Git 提交消息规范指南

我们对如何格式化 git 提交消息有非常精确的规则。这样可以查看更易读的消息,这些消息在查看项目历史记录时很容易理解。规范提交信息后,我们可以通过工具将 git commit
消息来生成 {工程项目} 更改日志
,每次版本发布都会有一个清晰的日记列表。

Commit Message Format

每个提交消息由 headerbodyfooter。  标头具有特殊格式,包括 typescopesubject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

所述 header 是必须的,而 scope 的报头的是可选的。

提交消息的任何行都不能超过100个字符!这允许在GitHub以及各种git工具中更容易阅读消息。

页脚应包含 closing reference to an issue (如果有).

(更多见 samples)

docs(changelog): update change log to beta.5
fix(release): need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

Revert

如果提交恢复先前的提交,则它应该以 revert:
,然后是还原提交的标头开头。在正文中它应该说:This reverts commit <hash>.
,其中哈希是被还原的提交的SHA。

Type

必须是以下之一:

  • build:影响构建系统或外部依赖项的更改(示例范围:gulp,broccoli,npm)

  • ci: 对CI配置文件和脚本的更改(示例范围:Travis,Circle,BrowserStack,SauceLabs)

  • docs: 只更改文档

  • feat: 一项新功能

  • fix: bug修复

  • perf: 改进性能的代码更改

  • refactor: 代码更改既不修复错误也不添加功能

  • style: 不影响代码含义的更改(空格,格式,缺少分号等)

  • test: 添加缺失测试或更正现有测试

Scope

范围应该是受影响的模块的名称(文件夹名称或其他有意义的单词),并且应该以模块为前缀:(由读取由提交消息生成的更改日志的人员感知

以下是一些例子:

  • module:alert

  • module:badge

  • module:breadcrumb

  • module:OTHER_COMPONENT_NAME


“使用模块名称”规则目前有一些例外:

  • packaging: 用于更改npm包布局的更改,例如公共路径更改,package.json更改,d.ts文件/格式更改,更改包等。

  • changelog: 用于更新CHANGELOG.md中的发行说明

  • showcase: 用于repo的/ showcase目录中的docs-app相关更改

  • none/empty string: 对所有包有用 style
    , test
    以及 refactor
    所做的更改 (e.g. style: add missing semicolons
    )

Subject

该主题包含对变更的简洁描述:

  • 使用命令式,现在时:“change” 而非 “changed” 和 “changes”

  • 不要把第一个字母大写

  • 最后没有点.号

Body

就像 subject 一样, 使用:“change” 而非 “changed” 和 “changes”。
body 应该包括改变的动机,并将其与之前的行为进行对比。

Footer

页脚应包含有关 Breaking Changes任何信息,也是引用此提交 Closes GitHub问题的地方。.

Breaking Changes 应该以 BREAKING CHANGE:
 带有空格或两个换行符的单词开头。然后将其余的提交消息用于此目的。

详细的解释请看这里 :

https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit

举例

以下是前端工程的提交日记举例:

英文原出处:

https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/CONTRIBUTING.md#-commit-message-guidelines

工具限制行为

利用 husky (哈士奇) 可以阻止一些不规范的 git commit, git push
 操作。使用方式见官方文档,比较详细。

以下是个人在项目的实践,package.json中加入 :

"husky": {
        "hooks": {
            "commit-msg": "node ./scripts/git/commit-msg.js -E HUSKY_GIT_PARAMS",
            "pre-commit": "pretty-quick --staged"
        }
    }


pre-commit

git commit 之前会触发 pre-commit
hooks,执行脚本 pretty-quick --staged
 ,用来自动格式化代码。格式化代码统一一个格式化工具,缩进等(可能会和编辑器配置文件.editorconfig
配合使用),保证整个项目在代码提交到仓库之前,都是统一的格式化风格,这样就不存在多个开发人员改一个文件,缩进时影响到很多代码行的问题了,对 CR 时体验较好。所以,这个步骤也是必不可少的。

1、需要安装两个模块:

npm i --save-dev prettier pretty-quick

2、配置规则文件 .prettierrc
 和  忽略文件 .prettierignore

.prettierrc

{
"singleQuote": true,
"printWidth": 120,
"tabWidth": 2,
"useTabs": false,
"overrides": [
{
"files": ".prettierrc",
"options": {
"parser": "json"
}
}
]
}

.prettierignore

**/*.md
**/*.svg
**/*.html
**/test.ts
**/*.less
coverage/
publish/
schematics/
site/
package.json
**/template/*
**/i18n/*

首次安装环境时,可以测试看效果

commit-msg

git commit 时,会触发 commit-msg
hooks,执行脚本 node ./scripts/git/commit-msg.js -E HUSKY_GIT_PARAMS

脚本可以参考 Angular 工程的 commit-msg.js,当 git message 不符合规范的时候,提交时检测不通过会有如下提示:


通过 commit-msg
pre-commit
 两个hooks,就可以阻止了开发人员不认真填写 git message 的行为了。更多hooks 可以看 git_hooks,根据自己的需要配置不同的脚本行为即可

总结

git message 规范化很重要,对版本更新信息的汇总管理,代码问题出现时,可能很好的追踪和查看修改记录,团队协作的情况下,是有必要进行管理的,吃过亏你就知道错了。Github上的开源项目,一般都会有很多相似规范的约束,这也是全球开源项目维护者、贡献者的协作的保障。有参与过开源项目 NG-ZORRO/ng-zorro-antd 的bug修改,这方面感受较多,建议开发者多了解或者有机会参与一些工程较规范的项目贡献。


文章超链接请阅读原文访问

文章转载自giscafer,如果涉嫌侵权,请发送邮件至:contact@modb.pro进行举报,并提供相关证据,一经查实,墨天轮将立刻删除相关内容。

评论