前端自动化之校验git commit & 自动生成Changelog 文件-[七日打卡1]

1,794 阅读4分钟

一、 什么是语义化的提交信息?

「语义化的提交信息」这一概念来自于 conventionalcommits.org ,被称为「约定式提交」。

约定式提交的优点有:

  • 可以创建清晰的提交历史
  • 使基于规范的自动化工具变得更加容易:如自动生成CHANGELOG
  • 减少bug、提高效率
  • 更加专业

约定式提交按照一种固定的模式就行书写,这样不仅有利于团队协作,还可以在项目后期通过自动化的方式生成一些文档。常见的公式如下所述。

公式

<类型>[可选的作用域]: <描述>
// 这里空一行
[可选的正文]
// 这里空一行
[可选的脚注]

描述是用于 git commit -m <message> 中 message 的格式。

scope作用域是非必填的:用于说明commit的影响范围,

比如一般分层项目的哪一层:数据层、业务逻辑层还是视图层,视项目不同而不同。

subjectcommit目的的简短描述:

  • 一般以动词开头
  • 首字母小写
  • 结尾不加句号

类型用于说明commit的类别,类型必填的

其中类型字段可以是下列选项中的一个:

  • feat: 表示新增的一个功能feature
  • fix: 表示该提交修复了一个bug
  • docs: 表示修改了文档
  • style: 表示修改了样式
  • refactor: 表示进行了代码重构
  • test: 表示进行了测试相关的工作
  • perf: 表示性能优化工作
  • chore: 琐事、杂项。不知道如何归类的就叫这个吧 :-)(chore这个单词本意是日常事务,乏味无聊的工作),指构建过程或者辅助工具的代码或配置变动

举个例子:

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

更多例子:

chore: add Oyster build script

docs: explain hat wobble

feat: add beta sequence
// 包含了可选的作用域
feat(lang): add polish language 

fix: remove broken confirmation message

// 为 fix 编写的提交说明,包含(可选的) issue 编号
fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

refactor: share logic between 4d3d3d3 and flarhgunnstow

style: convert tabs to spaces

test: ensure Tayne retains clothing

看下 vue.js 仓库的 commits 列表里截一张图,

会发现这种规范的commit管理方式看起来不仅专业,

而且有利于开源参与者理解每一条commit的意义。

更多详情可以参考文章:Commit message 和 Change log 编写指南

二、 自动lint git commit 消息

那么问题来了,如果有一个项目,从始至终都是你一个人在维护,那么你想怎么写都可以,没有人会干预你,但是如果是一个多人维护的项目,大家都有各自的想法,连「每行代码结尾是不是要加分号」这种的很难统一的行为,更何况是提交代码呢?

所以我们需要一个可以校验提交信息格式的工具:commitlint

安装

# 安装依赖
npm i husky lint-staged prettier @commitlint/cli @commitlint/config-conventional -D

配置

package.json中的相关配置:

"husky": {
    "hooks": {
      "pre-commit": "npm run lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  },
  "lint-staged": {
    "*.js": [
      "npm run prettier"
    ]
},

其中"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"这行表示当执行git commit时会使用 commitlint进行格式校验,

格式来自于配置文件:commitlint.config.js:

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

执行成功如图所示

三、自动生成 CHANGELOG.md 文件

如果你要开发一个对外的项目或工具,最好在仓库中提供一个CHANGELOG.md文件,供使用者查看项目的变更历史,有助于使用者更加了解你的项目。

原理

引用一句话:

Generate a changelog from git metadata

该工具是基于git commit 的提交信息生成的 chagelog 文件。

目前社区里用的比较多的是 angular提交规范

如何使用自动化的方式生成changelog文件,而不是项目作者手动维护呢?

推荐使用conventional-changelog这个npm,一条命令就可以自动生成好项目变更历史文件。

安装

项目源码在github上,感兴趣的可以去看一看。

# 安装
$ npm install -g conventional-changelog-cli

安装成功以后可以看一下这个命令行工具的帮助文档:

# 查看帮助
$ npx conventional-changelog --help

conventional-changelog.png

所以我们可以通过如下命令,便捷的生成变更历史记录:

# 生成 CHANGELOG.md 文件
$ conventional-changelog -p angular -u -i CHANGELOG.md -s -r 0

命令太长记不住怎么办? 放到npm scripts中:

// package.json
scripts: {
    "changelog": "conventional-changelog -p angular -u -i CHANGELOG.md -s -r 0"
}

以后只需要在命令行执行npm run changelog就可以了。

还有很多有趣又有用的功能等着大家去探索,有什么问题欢迎大家评论区留言。