使用 commitlint 约束项目 Git 代码提交描述信息格式规范

2019-09-24 0 条评论 5,328 次阅读 被赞了 3 次
本文发布于：2019-09-24，最后更新于：2020-12-30，如果内容失效请留言告知。
目录
[隐藏]

1 Angular Git Commit Guidelines 规范

Git 提交应当书写 commit message。message 的内容怎么写都行，但如何写比较合理是一个问题。开源社区有很多相关的规范，使用最广泛的则是Angular Git Commit Guidelines 规范，并且有众多相关的工具可以检测提交是否遵循了预定义的规范。

Angular 规范要求的 commit message 格式如下：

1
2
3
4
5
<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

可省略。详细描述本次提交，比如此次变更的动机、变更后与之前的差异等。

可省略。可以为 Breaking Changes 内容或关闭 issues 的关联语句。Breaking Changes 应当以 BREAKING CHANGE: 开头，然后在空格或两个空行后描述其详情。

2 引入 commitlint 约束前端项目遵循 Angular 规范

2.1 安装与配置 commitlint

commitlint 是当前使用最为广泛的 git commit 校验约束工具之一，使用它我们可以很方便的实现约束项目遵循 Angular 提交规范。

安装 commitlint：

1
2
3
npm i -D @commitlint/cli @commitlint/config-angular
// or
yarn add -D @commitlint/cli @commitlint/config-angular

在项目根目录新建 commitlint 的配置文件 commitlint.config.js，内容参考如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
'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：

1
2
3
npm i -D husky
// or
yarn add -D husky

在 package.json 中配置 husky：

1
2
3
4
5
6
"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 对该要求实现强制性约束。

1
2
3
4
5
6
7
8
9
10
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：

1
2
3
npm i -D conventional-changelog-cli
// or
yarn add -D conventional-changelog-cli

在 package.json 的 scripts 下加个脚本：

1
2
3
"scripts": {
  "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}

测试一下效果：

1
npm run chagelog

以上配置的语句默认为追加模式。执行如下语句可以生成完整的 CHANGELOG.md 文件：

1
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

相关文章:

一种自定义 Angular-cli 6.x/7.x 默认 webpack 配置的方法 Default Thumbnail升级至 Angular8 及实现自定义 webpack 配置的方案 升级至 Angular 13+ 后开发模式太慢的原因及构建性能优化 Default ThumbnailCSS 代码质量校验：stylelint 、stylefmt 及 post-sorting 的开发环境配置参考 Default ThumbnailAngular 文档生成：使用 compodoc 生成 Angular2+ 源码组件的 API 文档 Default ThumbnailAngular 中实现自定义组件的双向绑定的两种方法 Default Thumbnail在 Angular-cli 中引入 simple-mock 实现前端开发 API Mock 接口数据模拟 Default Thumbnailnodejs 执行失败报错 “JavaScript heap out of memory” 的解决办法 针对 websocket 服务代理与数据 mock 的方案 Default ThumbnailAngular 单元测试框架由 karma 迁移为 Jest 实践 正确区分开发与生产模式：移除调试代码的几种方法 Default Thumbnail一次 webpack dll 无效的场景原因分析与解决
点赞 (3)
知识共享许可协议
本作品采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可
  1. Pingback： 使用 typescript-starter 快速创建基于 TypeScript 的前端类库项目 - 志文工作室

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

Captcha Code