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

目录
[隐藏]

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,而不是changedchanges
  • 第一个字母小写
  • 结尾不加句号(.)

1.2 Body

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

可省略。可以为 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.jsonscripts 下加个脚本:

  "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
点赞 (3)

发表回复

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

Captcha Code