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
