本篇文章为《前端组件库的开发与维护》系列的第五篇文章。本文案例在线文档：calendar.hxkj.vip。GitHub 仓库：github.com/TangSY/vue3…。

为什么需要提交规范

有人说：代码提交到 Git 仓库的目的不就是为了备份代码吗？能提交上去就行了，搞什么提交规范，不要没事找事啊，保证代码不丢失，能正常跑就行！

既然如此，那费那么大劲搞提交规范到底是为啥呢？

其实呢，它的好处还真的不少。今天在这里给大伙简单的总结一下，对于开源组件库来说有以下五个方面的好处：

有助于他人更好的理解你的变更意图，更容易贡献/修改代码；
清晰的历史记录，方便快速浏览查找，回溯之前的内容；
规范的提交记录可用于自动生成版本发布日志(CHANGELOG.MD)；
结构化的提交信息有助于自动化脚本的识别和 CI/CD；
最重要的一条，体现了一个程序员的自我修养。

总的来讲就是有百利而无一害。

规范介绍

在众多规范当中，Conventional Commits 在市场上起主导地位，其主要来源于 AngularJS规范。这也是行业内使用最为广泛的 Git 提交信息规范，咱们今天就以该规范为例进行讲解：如何制定一套完整的代码提交规范。

该规范的提交信息由 Header、 Body 、Footer 三部分组成，Header 又包含 Type、Scope 和 Subject 三部分。格式如下：

Type(Scope):Subject

Body

Footer

Header、Body、Footer 三者之间用一个空行分隔。咱们日常开发中主要用到的就是 Header 部分，其他的基本用不上，就不花时间细讲了。

Header 包含 3 部分信息分别是：Type（必须）、Scope 和 Subject（必须）。格式如下：

Type(Scope):Subject

Type 用以说明提交的类别，建议的标识如下：

feat：新功能开发
fix：修复 BUG
docs：文档更新
style：代码格式调整，不影响代码整体运行
refactor：代码重构（没有新功能，也没有修复 BUG）
perf：性能优化
test：更新测试内容（包括增加）
chore：影响构建系统或外部依赖项的更改、对 CI/CD 配置文件的修改
revert：撤销之前提交

Scope 用以说明本次提交的影响范围，一般根据具体项目进行填写，比如具体修改了哪个组件、哪个文件等，文字尽量简短
Subject 用以对本次提交的概括说明，推荐以动词开头，如：设置、修改、增加、删减、撤销等，一般不超过 50 个字符。

例如下面这些提交信息，一眼就能看出每次提交都做了啥：

还有个大幅度提高用户体验的小技巧。如果是对其他人提出的 issue 进行修复的提交，可以在提交信息后面添加上该 issue 的编号，编号前面别忘了加个 # 号。这样的话，提交上去之后该编号会自动链接至相应的 issue 详情。(如果按照上述 Conventional Commits 规范，这个编号应该放在提交信息的 Footer 部分，但是 Footer 部分已经被我们舍弃了，所以就直接写在 Subject 末尾了)

而且 issue 详情里面也会自动添加一条链接，可以跳转至本次提交详情。

规范执行

规范制订好之后，那怎么确保每个提交都能符合规范呢。最好的方式就是通过特定的工具来生成和校验。

规范生成工具

commitizen 是一个命令行工具，可以通过交互的方式，生成符合规范的 git commit 信息。除此之外, 我们还需要为 commitizen 指定一个适配器，比如: cz-conventional-changelog。让 commitizen 按照我们指定的规范帮助我们生成 commit 信息。

咱们先来安装一下：

# 安装 commitizen
yarn add commitizen -D 
# 安装适配器
yarn add cz-conventional-changelog -D

然后在 package.json 中添加一个 scripts：

"commit": "git add . && git cz"

这样的话，后续提交代码时，用 yarn commit 代替即可，效果图如下：

如果不在 package.json 中添加 scripts 也不影响使用，但是执行命令得换成 npx git cz，执行效果是一样的：

假如你觉得上述的默认提交模板不能入你的法眼、全英文的你不喜欢、你还想加入一些 emoji 表情，可不可以？那当然是可以的。

这个时候，cz-customizable 就派上用场了，它允许咱们通过修改配置文件的方式自定义提交模板。

首先安装 cz-customizable

# 安装 cz-customizable
yarn add cz-customizable -D

然后在 package.json 中添加如下 config 配置：

···
"config": { 
  "commitizen": {
    "path": "node_modules/cz-customizable"
  } 
}
···

最后在项目根目录下创建 .cz-config.js 文件, 在该文件中配置你想要的模板，如何配置可查阅文档：传送门

这里提供一下我的配置文件，可供参考：

'use strict';

module.exports = {
  types: [
    {
      value: 'feat',
      name: '✨  feat:     新功能/特性',
    },
    {
      value: 'fix',
      name: '🐞  fix:      修复 BUG',
    },
    {
      value: 'refactor',
      name: '🛠   refactor: 代码重构',
    },
    {
      value: 'docs',
      name: '📚  docs:     只涉及文档变更',
    },
    {
      value: 'test',
      name: '🏁  test:     测试用例变更',
    },
    {
      value: 'chore',
      name: '🗯   chore:    只涉及依赖更新或构建工具配置的修改',
    },
    {
      value: 'style',
      name: '💅  style:    代码格式变更、样式变更等',
    },
    {
      value: 'revert',
      name: '⏪  revert:   撤销 commit 提交',
    },
  ],
  // 交互提示信息
  messages: {
    type: '确保本次提交遵循：前端代码提交规范！\n选择你要提交的类型：',
    scope: '\n选择一个 scope（可选）：',
    // 选择 scope: custom 时会出下面的提示
    customScope: '请输入自定义的 scope：',
    subject: '填写简短精炼的变更描述：\n',
    body: '填写更加详细的变更描述（可选）。使用 "|" 换行：\n',
    breaking: '列举非兼容性重大的变更（可选）：\n',
    footer: '列举出所有变更的 ISSUES CLOSED（可选）。 例如: #31, #34：\n',
    confirmCommit: '确认提交？',
  },
  scopes: [],
  allowCustomScopes: true,
  skipQuestions: ['body', 'breaking', 'footer'],
};

改完之后，重新执行 yarn commit ，效果图如下：

规范校验工具

commitlint: 可以帮助咱们校验 commit 信息, 如果我们提交的 commit 信息不符合指向的规范, 直接拒绝提交, 就是这么粗暴。

@commitlint/config-conventional：为 commitlint 量身定制的校验配置，该配置同样符合 AngularJS规范

首先安装这两个家伙：

yarn add @commitlint/config-conventional @commitlint/cli -D

然后在 package.json 文件中添加如下配置：

···
"commitlint": {
  "extends": [
    "@commitlint/config-conventional"
  ]
}
···

如果不想改 package.json 文件，在项目根目录新建 .commitlintrc.js 配置文件也是可以的，文件内容如下：

module.exports = { 
  extends: ['@commitlint/config-conventional'] 
}

校验工具安装完了并且已经配置好了，是不是意味着可以正常使用了？咱们来输入一些不规范的提交信息试试看：

可以看到，还是可以正常提交，难道是配置没生效？还是安装失败了？其实是因为没有触发校验机制。那咱们怎么触发呢？在什么时机触发呢？

由于 git 提供了hook机制，所以咱们可以在 commit-msg 阶段进行提交信息的校验，这里就需要请出 Husky 了。

首先，安装 Husky：

yarn add husky -D

同样的，需要在 package.json 文件中添加如下配置：

···
"husky": {
  "hooks": {
    "commit-msg": "commitlint -e $HUSKY_GIT_PARAMS"
  }
}
···

当然，如果你还是不想改 package.json 文件，在项目根目录新建 .huskyrc 配置文件也是可以的，文件内容如下：

{
  "hooks": {
    "commit-msg": "commitlint -e $HUSKY_GIT_PARAMS"
  }
}

接下来咱们还需要执行以下命令，在项目根目录下生成.husky文件夹：

npx husky install

最后使用以下命令在 .husky 文件夹中创建 commit-message hook 执行校验脚本：

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

可以看到 .husky 目录已经生成了：

那现在是不是意味着成功了呢？再试试不就知道了，随便输入不规范的提交信息：

完美，成功拦截！再来试试输入规范的提交信息：

总结

看到这里，相信大家都学会了如何优雅的提交代码，下一篇咱们来看看如何自动生成changelog。

对此系列感兴趣的，不妨一键三连（点赞 + 关注 + 收藏），方便跟进后续文章。

欢迎大家在评论区留下宝贵的建议！

本系列往期文章

开启掘金成长之旅！这是我参与「掘金日新计划 · 2 月更文挑战」的第 1 天，点击查看活动详情”

组件库从开发到维护全链路讲解（五）如何优雅的提交代码——规范化