共计 4177 个字符,预计需要花费 11 分钟才能阅读完成。
提醒:本文最后更新于2020-12-30 14:09,文中所关联的信息可能已发生改变,请知悉!
1 Angular Git Commit Guidelines 规范
Git 提交应当书写 commit message。message 的内容怎么写都行,但如何写比较合理是一个问题。开源社区有很多相关的规范,使用最广泛的则是Angular Git Commit Guidelines 规范,并且有众多相关的工具可以检测提交是否遵循了预定义的规范。
Angular 规范要求的 commit message 格式如下:
<type>(<scope>): <subject> | |
<空行> | |
<body> | |
<空行> | |
<footer> |
1.1 Header
包括三个字段:type(必需)、scope(可选)和subject(必需)。
1.1.1 Type
用于标识 commit 的类别,以便于快速识别本次提交的类型。只允许以下几个种标识:
- feat: 新功能
- fix: bug 修复
- docs: 文档变更
- style: 样式变更
- refactor: 重构(非新功能也不是bug修复的变动)
- perf: 性能优化改进
- test: 新增或修订单元测试
- chore: 构建过程或辅助工具变更
1.1.2 Scope
用于标识 commit 影响的范围,可以省略。
1.1.3 Subject
本次修改的简短描述。基本要求为:
- 以动词开头,使用第一人称现在时,比如
change
,而不是changed
或changes
- 第一个字母小写
- 结尾不加句号(.)
1.2 Body
可省略。详细描述本次提交,比如此次变更的动机、变更后与之前的差异等。
1.3 Footer
可省略。可以为 Breaking Changes
内容或关闭 issues
的关联语句。Breaking Changes
应当以 BREAKING CHANGE:
开头,然后在空格或两个空行后描述其详情。
2 引入 commitlint 约束前端项目遵循 Angular 规范
2.1 安装与配置 commitlint
commitlint
是当前使用最为广泛的 git commit 校验约束工具之一,使用它我们可以很方便的实现约束项目遵循 Angular 提交规范。
安装 commitlint
:
npm i -D @commitlint/cli @commitlint/config-angular | |
// or | |
yarn add -D @commitlint/cli @commitlint/config-angular |
在项目根目录新建 commitlint
的配置文件 commitlint.config.js
,内容参考如下:
'use strict'; | |
const message = process.env['HUSKY_GIT_PARAMS']; | |
const fs = require('fs'); | |
const types = [ | |
'build', // 构建执行 | |
'chore', // 构建工具相关 | |
'ci', // CI 相关 | |
'docs', // 文档更新 | |
'feat', // 新功能 | |
'fix', // bug 修复 | |
'perf', // 性能优化 | |
'refactor', // 功能重构 | |
'release', | |
'revert', // 回滚操作 | |
'style', // 样式变动 | |
'test', // 单元测试 | |
]; | |
const scopes = ['showcase', 'packaging', 'changelog', 'schematics', 'module:*']; | |
function parseMessage(message) { | |
const PATTERN = /^(\w+)(?:\(([^)]+)\))?\: (.+)$/; | |
const match = PATTERN.exec(message); | |
if (!match) { | |
return null; | |
} | |
return { | |
type: match[1] || null, | |
scope: match[2] || null, | |
}; | |
} | |
function getScopesRule() { | |
const messages = fs.readFileSync(message, { encoding: 'utf-8' }); | |
const parsed = parseMessage(messages.split('\n')[0]); | |
if (!parsed) { | |
return [2, 'always', scopes]; | |
} | |
const { scope, type } = parsed; | |
if (scope && !scopes.includes(scope) && type !== 'release' && !/module:.+/.test(scope)) { | |
return [2, 'always', scopes]; | |
} else { | |
return [2, 'always', []]; | |
} | |
} | |
module.exports = { | |
extends: ['@commitlint/config-angular'], | |
rules: { | |
'type-enum': [2, 'always', types], | |
'scope-enum': getScopesRule, | |
}, | |
}; |
上述示例我们使用了严格遵循 Angular 规范的 @commitlint/config-conventional
扩展,你也可以选择替换使用更为通用的 @commitlint/config-conventional
扩展。
更多配置规则可参考这里:
- https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-angular
- https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional
2.2 安装与配置 husky
这里其实还需借助另外一个工具 husky
,以实现 git hooks 注入与脚本配置执行。
安装 husky
:
npm i -D husky | |
// or | |
yarn add -D husky |
在 package.json
中配置 husky
:
"husky": { | |
"hooks": { | |
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS", | |
"pre-commit": "lint-staged" | |
} | |
}, |
如果一切操作顺利完成,接下来写个 commit 测试一下效果吧。
2.3 约束提交说明必须包含项目 issues 标记
在对项目质量有比较高的管控要求时,我们希望任何人不能随意提交未经讨论或评审过的代码。
当使用 gitlab 和 jira 并且将它们关联后,我们希望每次的代码提交都应当是与 jira 任务关联的。当 git 提交说明中包含 jira issues 编号,则 gitlab 会在该 issues 下的自动提交一个注释说明。
我们可以如下配置以借助 commitlint
对该要求实现强制性约束。
module.exports = { | |
'rules': { | |
'references-empty': [2, 'never'], | |
}, | |
parserPreset: { | |
parserOpts: { | |
issuePrefixes: ['PROJ-'] | |
} | |
}, | |
}; |
其中 PROJ-
为具体的 jira 项目编号前缀。
相关参考:
- https://docs.gitlab.com/ee/user/project/integrations/jira.html
- https://github.com/conventional-changelog/commitlint/issues/237
- https://github.com/conventional-changelog/commitlint/issues/372
- https://github.com/Gherciu/commitlint-jira
3 引入 conventional-changelog
生成项目变更日志
安装 conventional-changelog
:
npm i -D conventional-changelog-cli | |
// or | |
yarn add -D conventional-changelog-cli |
在 package.json
的 scripts
下加个脚本:
"scripts": { | |
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s" | |
} |
测试一下效果:
npm run chagelog
以上配置的语句默认为追加模式。执行如下语句可以生成完整的 CHANGELOG.md
文件:
npm run chagelog -- -s -r 0
相关参考:
- https://docs.gitlab.com/ee/user/project/integrations/jira.html
- https://github.com/conventional-changelog/commitlint/issues/237
- https://github.com/conventional-changelog/commitlint/issues/372
- https://github.com/Gherciu/commitlint-jira
相关参考
- https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit
- https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-angular
- https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional
- https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/commitlint.config.js
- https://github.com/conventional-changelog/conventional-changelog
- https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli
- https://github.com/conventional-changelog/standard-version