如何使用工具规范前端项目的commits与changelog技巧

软件发布|下载排行|最新软件

当前位置:首页IT学院IT技术

如何使用工具规范前端项目的commits与changelog技巧

Super_x   2023-03-20 我要评论

前言

项目的 Changelog 文件作为记录版本之间的差异和变更的主要“公示板”,主要用于传达一些关键的变更和指南,是直接与使用者对话的一种形式,所以 changelog 文件的整洁、直观一直是衡量一个项目质量的重要指标。

而且在我们翻阅一些组件库或者开源框架的 changelog 变动页的时候,经常看到一些项目的整齐、直观、井井有条如下面示例。这样的 log 日志必然不是手动排版出来的,大部分都是根据 commit 的描述自动生成的。

那么它们是如何配置,或者使用了什么工具包呢?想必大家都比较好奇。接下来我们就来一步一步揭开它神秘的面纱,并一步步的配置我们的组件库的 commit 规范,使我们的 commit 和 changelog 文件也能如此优雅。

示例一:semi 的 changelog 文件

示例二:antd 的 github changelog

Conventional Commits 规范

要保持 commit 信息的可读性,一个合理的 commit 格式规范是必不可少的,而 Conventional Commits 就是一种基于提交消息的轻量级约定。官方是这样描述它的:

它提供了一组用于创建清晰的提交历史的简单规则; 这使得编写基于规范的自动化工具变得更容易。 这个约定与SemVer相吻合, 在提交信息中描述新特性、bug 修复和破坏性变更。 --- Conventional Commits 官网

由此可以看出 Conventional Commits 是一个非常友好且清晰的规范,那遵循它的好处有哪些? 我们来进行一个总结:

  • 可格式化信息,自动产生 changelog;
  • 校验拦截不符合规则的 commit 描述;
  • 根据类型决定当前版本变更的性质;
  • 统一提交信息,有利于代码审查者的阅读。

那么 Conventional Commits 规则到底是如何的呢,我们接着往下看。通过官网的文档可以发现,它提交说明的结构如下所示:

<类型>[可选的作用域]: <描述>
[可选的正文]
[可选的脚注]
举例:
fix(docs): 修复文档中字符错误
feat(components): tooltip 组件初始化

可以看到,结构里面包含类型、作用域、描述、正文、脚注。

  • 类型:用来标示当前提交是一个什么样的类型,比如最常见的有 fixfeat 等,用来标示当前的提交是一个修复类的操作,或者一个新功能的增加。可枚举的类型还有:choredocsstylerefactorperftest 等。这块可以参照 @commitlint/config-conventional 里面的枚举值。
  • 作用域:此字段可自行定义枚举值,根据业务模块划分即可,比如:当前是【文档】的改动就可以填写 docs;当前影响了 utils 库,就可以填写 feat(utils):等等,取值不限制。
  • 描述:描述就是对当前 commit 的简短描述,尽量简短,清晰。

对于简短描述的扩充填写,可选

  • 脚注:包含关于提交的元信息,比如:有关联的请求url、cr人员、等等一些关键性信息。
  • 特别需要注意的是:在可选的正文或脚注的起始位置带有 BREAKING CHANGE: 的提交,表示引入了破坏性 API 变更(这和语义化版本中的 MAJOR 相对应)。 破坏性变更可以是任意类型提交的一部分。

可以看出 Conventional Commits 规范非常高效且上手难度很低,并且 Conventional Commits 已经被很多知名的开源项目所集成,是一个被大家广泛接受的标准。而我们的组件库也需要遵循它来规范我们的 commit。

要如何遵循此规范呢?用插件来约束我们的 commit 是一个比较好的解决方案。接下来,我们来看下有哪些插件可以让我们愉快的使用。

哪些工具可以组合起来规范我们的 commit?

Commitizen

上面我们说到了 Conventional Commits 规范,我们要遵循此规范时,可能手动去处理 commit 信息会比较繁琐,并且出错率也很高,比如在我们书写 fix(scope): xxx 时,很容易对于符合的全角还是半角输入法搞混,这样很容易造成信息格式化的失败。那么我们该如何高效稳定的遵循 Conventional Commits 规范呢?Commitizen 应声而来。

Commitizen 可以说是一个交互性日志提交工具,用于辅助开发者提交符合规范的 commit 信息。它可以说是提供了“保姆式”的提交体验,在我们触发 commit 的脚本后,只需要根据提示来选择我们的提交信息,就可以生成一个符合规范的 commit。

? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature 
  fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) 
  refactor: A code change that neither fixes a bug nor adds a feature 
  perf:     A code change that improves performance 
  test:     Adding missing tests or correcting existing tests 
(Move up and down to reveal more choices)

cz-customizable

cz-customizable 作为一个用于自定义 Commitizen 的扩展插件,可以在原生 Commitizen 的标准上,根据配置文件来自定义我们的提交规范。可以说是用来扩展 Commitizen 的神器。一般都用于 Commitizen 的配套使用。

Copyright 2022 版权所有 软件发布 访问手机版

声明:所有软件和文章来自软件开发商或者作者 如有异议 请与本站联系 联系我们