轻松解决规范化Git Commit

前言

规范化 git commit 对于提高 git log 可读性、可控的版本控制和 changelog 生成都有着重要的作用。然而阻碍我们脚步的不只是团队的推广,单单对于一系列工具的配置都让人头大。这其中主要就是 commitlint 和 commitizen 的配合使用以及自定义提交规范。本文总结了目前的最佳实践给大家,如果有帮助,赏个star足矣。

Conventional Commits 约定式提交规范

Conventional Commits 是一种用于给提交信息增加人机可读含义的规范。约定式提交规范是一种基于消息的轻量级约定。它提供了一组用于创建清晰的提交历史的简单规则;这使得编写基于规范的自动化工具变得更容易。这个约定与 SemVer 相吻合,在提交信息中描述新特性、bug 修复和破坏性变更。
提交说明的结构如下所示:

类型(type)

feat:: 类型为 feat 的提交表示在代码库中新增了一个功能(这和语义化版本中的 MINOR 相对应)。
fix::类型为 fix 的 提交表示在代码库中修复了一个 bug (这和语义化版本中的 PATCH 相对应)。
docs:: 只是更改文档。
style:: 不影响代码含义的变化(空白、格式化、缺少分号等)。
refactor:: 代码重构,既不修复错误也不添加功能。
perf:: 改进性能的代码更改。
test:: 添加确实测试或更正现有的测试。
build:: 影响构建系统或外部依赖关系的更改(示例范围:gulp、broccoli、NPM)。
ci:: 更改持续集成文件和脚本(示例范围:Travis、Circle、BrowserStack、SauceLabs)。
chore:: 其他不修改src或test文件。
revert:: commit 回退。

范围(scope)

可以为提交类型添加一个围在圆括号内的作用域,以为其提供额外的上下文信息。例如 feat(parser): adds ability to parse arrays.。

BREAKING CHANGE

在可选的正文或脚注的起始位置带有 BREAKING CHANGE: 的提交,表示引入了破坏性 API 变更(这和语义化版本中的 MAJOR 相对应)。 破坏性变更可以是任意 类型 提交的一部分。

示例

包含了描述以及正文内有破坏性变更的提交说明
feat: allow provided config object to extend other configs

BREAKING CHANGE: extends key in config file is now used for extending other config files

包含了可选的 ! 字符以提醒注意破坏性变更的提交说明
chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

不包含正文的提交说明
docs: correct spelling of CHANGELOG

包含作用域的提交说明
feat(lang): add polish language

为 fix 编写的提交说明,包含(可选的) issue 编号

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

约定式提交规范

  1. 每个提交都必须使用类型字段前缀,它由一个名词组成,诸如feat或fix,其后接一个可选的作用域字段,以及一个必要的冒号(英文半角)和空格。
  2. 当一个提交为应用或类库实现了新特性时,必须使用feat类型。
  3. 当一个提交为应用修复 bug 时,必须使用fix类型。
  4. 作用域字段可以跟随在类型字段后面。作用有必须是一个描述某部分代码的名词,并用圆括号包围,例如:fix(parser):
  5. 描述字段必须紧接在类型/作用域前缀的空格之后。描述指的是对代码变更的简短总结,例如:fix:array parsing issue
    when multiplejspaces were contained in string。
  6. 在简短描述之后,可以编写更长的提交正文,为代码变更提供额外的上下文信息。正文必须起始于描述字段结束的一个空行后。
  7. 在正文结束的一个空行之后,可以编写一行或或多行脚注。脚注必须包含关于提交的元信息,例如:关联的合并请求、Reviewer、破坏性变更、每条元信息一行。
  8. 破坏性变更必须标示在正文区域最开始处,或脚注区域中某一行的开始。一个破坏性变更必须包含大写的文本BREAKING
    CHANGE,后面紧跟冒号和空格。
  9. 在BREAKING CHANGE:之后必须提供描述,以描述对 API 的变更。例如:BREAKING CHANGE:
    enviroment variables now take precedence over cofig files。
  10. 在提交说明中,可以使用feat和fix之外的类型。
  11. 工具的实现必须不区分大小写地解析构成约定式提交的信息单元,只有BREAKING CHANGE 必须是大写的。
  12. 可以在类型/作用域前缀之后,:之前,附加!字符,以进一步提醒注意破坏性变更。当有!前缀时,正文或脚注内必须包含BREAKING
    CHANGE: description

为什么使用约定式提交

  1. 自动化生产 CHANGELOG。
  2. 基于提交的类型,自动决定语义化的版本变更。
  3. 向同事、公众与其他利益关系者传达变化的性质。
  4. 触发构建和部署流程。
  5. 让人们探索一个更加结构化的提交历史,以便降低对你的项目作出贡献的难度。

cz-customizable

可自定义的Commitizen插件(或独立实用运行)可帮助实现一致的提交消息。
安装 cz-customizable:
$ yarn add cz-customizable -D
复制代码
向 package.json 添加新的 script:
{
“scripts” : {

“commit”: “./node_modules/cz-customizable/standalone.js”
}
}

在根目录新建 .cz-config.js 并复制 cz-config-EXAMPLE.js 到文件。
效果:

commitlint
commitlint检查您的提交消息是否符合conventional commit format。
1、安装 @commitlint/cli、husky:
$ yarn add -D @commitlint/cli husky

2、添加 git commit hooks 到 package.json:
{

“husky”: {
“hooks”: {
“commit-msg”: “commitlint -E HUSKY_GIT_PARAMS”
}
}
}

3、安装 commitlint-config-cz:
commitlint-config-cz 合并 cz-customizable 的配置 {types,scopes,scopeOverrides} 和 commitlint 的配置 {type-enum,scope-enum}。这样,你就可以在一个地方维护 types 和 scopes。
$ yarn add commitlint-config-cz -D
复制代码
4、在 commitlint.config.js 中用 cz 扩展您的 commitlint 配置:
module.exports = {
extends: [‘cz’],
rules: {
// must add these rules
‘type-empty’: [2, ‘never’],
‘subject-empty’: [2, ‘never’]
}
};

vscode commitizen
在 VS Code 中搜索装 vscode commitizen,然后就可以摆脱命令行了,而且这个插件是和前面所有的配置兼容的,效果如下:

GitHub Actions
新建一个 github workflow .github/workflows/commitlint.yml,作用是在提交 pull_request 时,检查信息:
name: Lint Commit Messages
on: [pull_request]

jobs:
commitlint:
runs-on: ubuntu-latest
steps:

  • uses: actions/checkout@v2
    with:
    fetch-depth: 0
  • uses: actions/setup-node@v1
    with:
    node-version: ‘10.x’
  • run: npm install
  • name: Add dependencies for commitlint action

G I T H U B W O R K S P A C E i s t h e p a t h t o y o u r r e p o s i t o r y r u n : e c h o " : : s e t − e n v n a m e = N O D E P A T H : : GITHUB_WORKSPACE is the path to your repository run: echo "::set-env name=NODE_PATH::GITHUBW​ORKSPACEisthepathtoyourrepositoryrun:echo"::set−envname=NODEP​ATH::GITHUB_WORKSPACE/node_modules"

Now the commitlint action will run considering its own dependencies and yours as well 🚀

  • uses: wagoid/commitlint-github-action@v2

standard-version
standard-version 是一款遵循语义化版本( semver)和 commit message 标准规范 的版本和 changelog 自动化工具。通常情况线下,我们会在 master 分支进行如下的版本发布操作:

git pull origin master
根据 package.json 中的 version 更新版本号,更新 CHANGELOG
git add .
git commit
git tag 打版本操作
git push --tags:push 版本 tag 和 master 分支到仓库

其中 2,3,4,5 是 standard-version 工具会自动完成的工作,配合本地的 shell 脚本,则可以自动完成一系列版本发布的工作了。

安装 & 使用

$ yarn add -D standard-version

// package.json
{
“scripts”: {
“release”: “standard-version”
}
}

First Release:yarn release --first-release
Cutting Release:yarn release
Release as a Pre-Release:yarn release --prerelease or yarn release --prerelease alpha
Release as a Target Type Imperatively (npm version-like):yarn release --release-as minor or yarn release --release-as 1.1.0,可以合并 --prerelease以此方便发布实验性特性
Prevent Git Hooks:yarn release --no-verify

©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 206,214评论 6 481
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 88,307评论 2 382
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 152,543评论 0 341
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 55,221评论 1 279
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 64,224评论 5 371
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,007评论 1 284
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,313评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,956评论 0 259
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 43,441评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,925评论 2 323
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,018评论 1 333
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,685评论 4 322
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,234评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,240评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,464评论 1 261
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,467评论 2 352
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,762评论 2 345