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

2019-09-24 0 条评论 5,183 次阅读 被赞了 3 次
目录
[隐藏]

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

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

可省略。可以为 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

相关文章:

一种自定义 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 项目升级至 Angular6 Default Thumbnail如何保障前端项目代码质量 Default ThumbnailAngular 9 新特性及 Angular 8 升级至 Angular 9 参考 针对 websocket 服务代理与数据 mock 的方案 Default Thumbnail使用 npm-check-updates 快速升级前端项目 package.json 依赖版本
点赞 (3)
知识共享许可协议
本作品采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可
  1. Pingback： 使用 typescript-starter 快速创建基于 TypeScript 的前端类库项目 - 志文工作室

发表回复

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

Captcha Code