You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
'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 followsmessages: {type: 'Select the type of change that you\'re committing:',scope: '\nDenote the SCOPE of this change (optional):',// used if allowCustomScopes is truecustomScope: '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 lengthsubjectLimit: 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 followsmessages: {type: '选择一种你的提交类型:',scope: '选择一个scope (可选):',// used if allowCustomScopes is truecustomScope: 'Denote the SCOPE of this change:',subject: '短说明:\n',body: '长说明,使用"|"换行(可选):\n',breaking: '非兼容性说明 (可选):\n',footer: '关联关闭的issue,例如:#31, #34(可选):\n',confirmCommit: '确定提交说明?'},allowCustomScopes: true,allowBreakingChanges: ['特性','修复'],// limit subject lengthsubjectLimit: 100};
在多人协作的项目中,如果Git的提交说明精准,在后期协作以及Bug处理时会变得有据可查,项目的开发可以根据规范的提交说明快速生成开发日志,从而方便开发者或用户追踪项目的开发信息和功能特性。
本文主要内容:
这里提供演示项目地址:cz-example,如果您感兴趣,希望可以Star一下。
Git的提交说明
Git每次提交代码的时候都需要手写提交说明(Commit message):
书写多行可以使用以下命令:
此时会跳出一个文本编辑器,可以在文本编辑器中书写多行提交说明:
如果没有规范的提交说明,很难阐述当前代码的提交性质(修复Bug、代码性能优化、新增功能或者发布版本等)。查看Vue项目的Git提交说明(
fix
表明修复问题、feat
表明新增功能...),它完全符合Angular规范:手写符合规范的提交说明很难避免错误,可以借助工具来实现规范的提交说明。
规范的Git提交说明
commit
,便于筛选代码review
commit
生成更新日志Git
提交说明结构Git
提交说明可分为三个部分:Header
、Body
和Footer
。Header
Header
部分包括三个字段type
(必需)、scope
(可选)和subject
(必需)。type
type
用于说明commit
的提交性质。scope
scope
说明commit
影响的范围。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工具:
Commitizen适配器
cz-conventional-changelog
如果需要在项目中使用commitizen生成符合AngularJS规范的提交说明,初始化cz-conventional-changelog适配器:
如果当前已经有其他适配器被使用,则会报以下错误,此时可以加上
--force
选项进行再次初始化初始化命令主要进行了3件事情
在项目中安装cz-conventional-changelog 适配器依赖
将适配器依赖保存到
package.json
的devDependencies
字段信息在
package.json
中新增config.commitizen
字段信息,主要用于配置cz工具的适配器路径:接下来可以使用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适配器路径:
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,如下所示:这里对其进行汉化处理(只是为了说明定制说明的一个示例):
再次使用
git cz
命令进行提交说明:从上图可以看出此时的提交说明选项已经汉化,继续填写提交说明:
把代码提交到远程看看效果:
Commitizen校验
commitlint
校验提交说明是否符合规范,安装校验工具commitlint:
@commitlint/config-conventional
安装符合Angular风格的校验规则
在项目中新建
commitlint.config.js
文件并设置校验规则:安装huksy(git钩子工具)
在package.json中配置
git commit
提交时的校验钩子:需要注意,使用该校验规则不能对
.cz-config.js
进行不符合Angular规范的定制处理,例如之前的汉化,此时需要将.cz-config.js
的文件按照官方示例文件cz-config-EXAMPLE.js进行符合Angular风格的改动。执行错误的提交说明:
执行符合Angular规范的提交说明:
commitlint-config-cz
如果是使用cz-customizable适配器做了破坏Angular风格的提交说明配置,那么不能使用**@commitlint/config-conventional**规则进行提交说明校验,可以使用commitlint-config-cz对定制化提交说明进行校验。
安装校验规则:
然后加入commitlint校验规则配置:
validate-commit-msg
除了使用commitlint校验工具,也可以使用validate-commit-msg校验工具对cz提交说明是否符合Angular规范进行校验。
Commitizen日志
如果使用了cz工具集,配套conventional-changelog可以快速生成开发日志:
在
pacage.json
中加入生成日志命令:You could follow the following workflow
执行
npm run version
后可查看生产的日志CHANGELOG.md。Vue CLI 3 插件
如果对于上述所说的配置感到繁琐,这里提供一个Vue CLI 3的插件,如果开发的项目由Vue CLI 3系统生成,可以使用插件
@ziyi2/ui-cz
一键生成:该插件采用了cz-customizable定制化提交说明的适配器、@commitlint/config-conventional校验规则以及conventional-changelog日志生成器。
总结
呼吁大家书写规范的提交说明,代码说明不规范,项目成员泪两行。这里再次提供演示项目地址:cz-example,如果您感兴趣,希望可以Star一下。
链接
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钩子文档
The text was updated successfully, but these errors were encountered: