Cz工具集使用介绍 - 规范Git提交说明

时间 2019-11-05 标签 cz 工具集使用介绍规范 git 提交说明

在多人协做的项目中，若是Git的提交说明精准，在后期协做以及Bug处理时会变得有据可查，项目的开发能够根据规范的提交说明快速生成开发日志，从而方便开发者或用户追踪项目的开发信息和功能特性。javascript

本文主要内容：vue

介绍符合Angular规范（须要翻墙）的提交说明
介绍提交说明工具集cz（适配器、校验以及日志）的使用方法
介绍供开发者快速生成项目cz工具集的Vue CLI 3插件@ziyi2/ui-cz

这里提供演示项目地址：cz-example。java

Git的提交说明

Git每次提交代码的时候都须要手写提交说明（Commit message）：node

git commit -m "hello world"
复制代码

书写多行可使用如下命令：webpack

git commit
复制代码

此时会跳出一个文本编辑器，能够在文本编辑器中书写多行提交说明：git

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch master
# Your branch is up to date with 'origin/master'.
#
# Changes to be committed:
#       new file:   package.json
#
G:/git-lab/cz/.git/COMMIT_EDITMSG [unix] (19:49 24/01/2019)   
复制代码

若是没有规范的提交说明，很难阐述当前代码的提交性质（修复Bug、代码性能优化、新增功能或者发布版本等）。查看Vue项目的Git提交说明（fix代表修复问题、feat代表新增功能...），它彻底符合Angular规范：github

手写符合规范的提交说明很难避免错误，能够借助工具来实现规范的提交说明。web

规范的Git提交说明

提供更多的历史信息，方便快速浏览
能够过滤某些commit，便于筛选代码review
能够追踪commit生成更新日志
能够关联issues

`Git`提交说明结构

Git提交说明可分为三个部分：Header、Body和Footer。vue-cli

<Header> <Body> <Footer>
复制代码

`Header`

Header部分包括三个字段type（必需）、scope（可选）和subject（必需）。npm

<type>(<scope>): <subject>
复制代码

Vue源码的提交说明省略了scope。

`type`

type用于说明 commit 的提交性质。

值	描述
feat	新增一个功能
fix	修复一个Bug
docs	文档变动
style	代码格式（不影响功能，例如空格、分号等格式修正）
refactor	代码重构
perf	改善性能
test	测试
build	变动项目构建或外部依赖（例如scopes: webpack、gulp、npm等）
ci	更改持续集成软件的配置文件和package中的scripts命令，例如scopes: Travis, Circle等
chore	变动构建流程或辅助工具
revert	代码回退

`scope`

scope说明commit影响的范围。scope依据项目而定，例如在业务项目中能够依据菜单或者功能模块划分，若是是组件库开发，则能够依据组件划分。

提示：scope能够省略。

`subject`

subject是commit的简短描述。

`Body`

commit的详细描述，说明代码提交的详细说明。

`Footer`

若是代码的提交是不兼容变动或关闭缺陷，则Footer必需，不然能够省略。

不兼容变动

当前代码与上一个版本不兼容，则Footer以BREAKING CHANGE开头，后面是对变更的描述、以及变更的理由和迁移方法。

关闭缺陷

若是当前提交是针对特定的issue，那么能够在Footer部分填写须要关闭的单个 issue 或一系列issues。

Commitizen

commitizen/cz-cli是一个能够实现规范的提交说明的工具：

When you commit with Commitizen, you'll be prompted to fill out any required commit fields at commit time. No more waiting until later for a git commit hook to run and reject your commit (though that can still be helpful). No more digging through CONTRIBUTING.md to find what the preferred format is. Get instant feedback on your commit message formatting and be prompted for required fields.

提供选择的提交信息类别，快速生成提交说明。安装cz工具:

npm install -g commitizen
复制代码

Commitizen适配器

cz-conventional-changelog

若是须要在项目中使用commitizen生成符合AngularJS规范的提交说明，初始化cz-conventional-changelog适配器：

commitizen init cz-conventional-changelog --save --save-exact
复制代码

若是当前已经有其余适配器被使用，则会报如下错误，此时能够加上--force选项进行再次初始化

Error: A previous adapter is already configured. Use --force to override
复制代码

初始化命令主要进行了3件事情

在项目中安装cz-conventional-changelog 适配器依赖
将适配器依赖保存到package.json的devDependencies字段信息
在package.json中新增config.commitizen字段信息，主要用于配置cz工具的适配器路径：

"devDependencies": {
 "cz-conventional-changelog": "^2.1.0"
},
"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}
复制代码

接下来可使用cz的命令git cz代替git commit进行提交说明：

代码提交到远程的Github后，能够在相应的项目中进行查看，例如（这里使用feat不是很合适，只是一个示例）：

cz-customizable

若是想定制项目的提交说明，可使用cz-customizable适配器：

Suitable for large teams working with multiple projects with their own commit scopes. When you specify the scopes in your .cz-config.js, cz-customizable allows you to select the pre-defined scopes. No more spelling mistakes embarrassing you when generating the changelog file.

安装适配器

npm install cz-customizable --save-dev

将以前符合Angular规范的cz-conventional-changelog适配器路径改为cz-customizable适配器路径：

"devDependencies": {
  "cz-customizable": "^5.3.0"
},
"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}
复制代码

cz-customizable will first look for a file called .cz-config.js，alternatively add a config block in your package.json。

官方提供了一个.cz-config.js示例文件cz-config-EXAMPLE.js，以下所示：

'use strict';

module.exports = {

  types: [
    {value: 'feat',     name: 'feat: A new feature'},
    {value: 'fix',      name: 'fix: A bug fix'},
    {value: 'docs',     name: 'docs: Documentation only changes'},
    {value: 'style',    name: 'style: Changes that do not affect the meaning of the code\n (white-space, formatting, missing semi-colons, etc)'},
    {value: 'refactor', name: 'refactor: A code change that neither fixes a bug nor adds a feature'},
    {value: 'perf',     name: 'perf: A code change that improves performance'},
    {value: 'test',     name: 'test: Adding missing tests'},
    {value: 'chore',    name: 'chore: Changes to the build process or auxiliary tools\n and libraries such as documentation generation'},
    {value: 'revert',   name: 'revert: Revert to a commit'},
    {value: 'WIP',      name: 'WIP: Work in progress'}
  ],

  scopes: [
    {name: 'accounts'},
    {name: 'admin'},
    {name: 'exampleScope'},
    {name: 'changeMe'}
  ],

  // it needs to match the value for field type. Eg.: 'fix'
  /* scopeOverrides: { fix: [ {name: 'merge'}, {name: 'style'}, {name: 'e2eTest'}, {name: 'unitTest'} ] }, */
  // override the messages, defaults are as follows
  messages: {
    type: 'Select the type of change that you\'re committing:',
    scope: '\nDenote the SCOPE of this change (optional):',
    // used if allowCustomScopes is true
    customScope: 'Denote the SCOPE of this change:',
    subject: 'Write a SHORT, IMPERATIVE tense description of the change:\n',
    body: 'Provide a LONGER description of the change (optional). Use "|" to break new line:\n',
    breaking: 'List any BREAKING CHANGES (optional):\n',
    footer: 'List any ISSUES CLOSED by this change (optional). E.g.: #31, #34:\n',
    confirmCommit: 'Are you sure you want to proceed with the commit above?'
  },

  allowCustomScopes: true,
  allowBreakingChanges: ['feat', 'fix'],

  // limit subject length
  subjectLimit: 100
  
};
复制代码

这里对其进行汉化处理（只是为了说明定制说明的一个示例）：

'use strict';

module.exports = {

  types: [
    {value: '特性',     name: '特性: 一个新的特性'},
    {value: '修复',      name: '修复: 修复一个Bug'},
    {value: '文档',     name: '文档: 变动的只有文档'},
    {value: '格式',    name: '格式: 空格, 分号等格式修复'},
    {value: '重构', name: '重构: 代码重构，注意和特性、修复区分开'},
    {value: '性能',     name: '性能: 提高性能'},
    {value: '测试',     name: '测试: 添加一个测试'},
    {value: '工具',    name: '工具: 开发工具变更(构建、脚手架工具等)'},
    {value: '回滚',   name: '回滚: 代码回退'}
  ],

  scopes: [
    {name: '模块1'},
    {name: '模块2'},
    {name: '模块3'},
    {name: '模块4'}
  ],

  // it needs to match the value for field type. Eg.: 'fix'
  /* scopeOverrides: { fix: [ {name: 'merge'}, {name: 'style'}, {name: 'e2eTest'}, {name: 'unitTest'} ] }, */
  // override the messages, defaults are as follows
  messages: {
    type: '选择一种你的提交类型:',
    scope: '选择一个scope (可选):',
    // used if allowCustomScopes is true
    customScope: 'Denote the SCOPE of this change:',
    subject: '短说明:\n',
    body: '长说明，使用"|"换行(可选)：\n',
    breaking: '非兼容性说明 (可选):\n',
    footer: '关联关闭的issue，例如：#31, #34(可选):\n',
    confirmCommit: '肯定提交说明?'
  },

  allowCustomScopes: true,
  allowBreakingChanges: ['特性', '修复'],

  // limit subject length
  subjectLimit: 100

};
复制代码

再次使用git cz命令进行提交说明：

从上图能够看出此时的提交说明选项已经汉化，继续填写提交说明：

把代码提交到远程看看效果：

Commitizen校验

commitlint

校验提交说明是否符合规范，安装校验工具commitlint：

npm install --save-dev @commitlint/cli
复制代码

@commitlint/config-conventional

安装符合Angular风格的校验规则

npm install --save-dev @commitlint/config-conventional 
复制代码

在项目中新建commitlint.config.js文件并设置校验规则：

module.exports = {
  extends: ['@commitlint/config-conventional']
};
复制代码

安装huksy（git钩子工具）

npm install husky --save-dev
复制代码

在package.json中配置git commit提交时的校验钩子：

"husky": {
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }  
}
复制代码

须要注意，使用该校验规则不能对.cz-config.js进行不符合Angular规范的定制处理，例如以前的汉化，此时须要将.cz-config.js的文件按照官方示例文件cz-config-EXAMPLE.js进行符合Angular风格的改动。

执行错误的提交说明：

执行符合Angular规范的提交说明：

commitlint须要配置一份校验规则，@commitlint/config-conventional就是符合Angular规范的一份校验规则。

commitlint-config-cz

若是是使用cz-customizable适配器作了破坏Angular风格的提交说明配置，那么不能使用**@commitlint/config-conventional**规则进行提交说明校验，可使用commitlint-config-cz对定制化提交说明进行校验。

安装校验规则：

npm install commitlint-config-cz --save-dev
复制代码

而后加入commitlint校验规则配置：

module.exports = {
  extends: [
    'cz'
  ]
};
复制代码

这里推荐使用**@commitlint/config-conventional**校验规则，若是想使用cz-customizable适配器，那么定制化的配置不要破坏Angular规范便可。

validate-commit-msg

除了使用commitlint校验工具，也可使用validate-commit-msg校验工具对cz提交说明是否符合Angular规范进行校验。

Commitizen日志

若是使用了cz工具集，配套conventional-changelog能够快速生成开发日志：

npm install conventional-changelog -D
复制代码

在pacage.json中加入生成日志命令：

"version": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"
复制代码

You could follow the following workflow

Make changes
Commit those changes
Pull all the tags
Run the npm version [patch|minor|major] command
Push

执行npm run version后可查看生产的日志CHANGELOG.md。

注意要使用正确的Header的type，不然生成的日志会不许确，这里只是一个示例，生成的日志不是很严格。

Vue CLI 3 插件

若是对于上述所说的配置感到繁琐，这里提供一个Vue CLI 3的插件，若是开发的项目由Vue CLI 3系统生成，可使用插件@ziyi2/ui-cz一键生成：

vue add @ziyi2/ui-cz
复制代码

该插件采用了cz-customizable定制化提交说明的适配器、@commitlint/config-conventional校验规则以及conventional-changelog日志生成器。

总结

呼吁你们书写规范的提交说明，代码说明不规范，项目成员泪两行。演示项目地址：cz-example。

连接

Angular规范
cz-cli - cz工具
cz-customizable - cz适配器
@commitlint/config-conventional - cz适配器
commitlint - cz校验工具
commitlint-config-cz - cz校验工具的校验规则
validate-commit-msg - cz校验工具
conventional-changelog - cz日志生成器
commit_msg - git钩子文档