Skip to content

Latest commit

 

History

History
348 lines (218 loc) · 11.7 KB

standard.md

File metadata and controls

348 lines (218 loc) · 11.7 KB

git 与 语义化规范

Git commit 规范

作用

  • 能加快 Code Review 的流程
  • 根据 Git Commit 的元数据生成 Changelog
  • 后续维护者可以知道 Feature 被修改的原因

 

技术方案

其实社区有多种 Commit message 的写法规范，我们这里使用 Angular 规范，这是目前使用最广的写法。如下图所示：

 

提交的格式要求

一般提交格式的要求如下图：

type

type 代表了某次提交的类型，比如是修复一个 bug 还是增加了一个新的 feature。所有的type 类型如下：

  • feat：新增 feature
  • fix：修复 bug
  • docs：仅仅修改了文档，比如 README、CHANGLELOG 等等
  • style：仅仅修改了空格、格式缩进、多行等等，不改变逻辑
  • refactor：代码重构，没有加新的功能或者修复 bug
  • perf：优化相关，比如提升性能、体验等
  • test：测试用例，包括单元测试、集成测试等
  • chore：改变构建流程，或者增加依赖库、工具等
  • revert：回滚到上一个版本

Scope

scope 字段用于说明本次 commit 所影响的范围，比如视图层、数据模型或者路由模块等，是一个可选参数。

subject

subject 字段是本次 commit 的一个概要，需要用最简洁的语言来说明本次修改的内容。

Body

可以使用多行文本详细地说明本次提交所改动的一些细节，从而帮助后续的使用者们更好地了解代码的内容。

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent

案例取自 阮一峰老师的 Commit message 和 Change log 编写指南

Footer

Footer 部分只用于两种情况。

  • 不兼容变动

如果本次的 commit 与前一个版本的代码无法兼容，那么 Footer 部分需要以 BREAKING CHANGE 开头，后面描述本次变动的详细情况以及迁移到新版本代码的方法。

BREAKING CHANGE: isolate scope bindings definition has changed.

  To migrate the code follow the example below:

  Before:

  scope: {
    myAttr: 'attribute',
  }

  After:

  scope: {
    myAttr: '@',
  }

  The removed `inject` wasn't generaly useful for directives so there should be no code using it.

案例取自 阮一峰老师的 Commit message 和 Change log 编写指南

  • 关闭 Issue

如果当前 commit 针对某个 issue，那么可以在 Footer 部分关闭这个 issue 。以 Close 开头，后面用 # 号标识对应的 Issue 号码。

Closes #123, #245, #992

 

validate-commit-msg

我们使用 validate-commit-msg 在提交之前验证 commit 信息是否符合要求。同时我们使用 husky 来为本地开发阶段增加 precommit 钩子

安装

npm install validate-commit-msg husky -D

配置

我们在 packages.json 中新增下面几行代码：

// ...
"husky": {
  "hooks": {
    "commit-msg": "validate-commit-msg"
  }
},
// ...

现在当我们在命令行以 git commit -m '添加代码一波' 这样的 commit 形式提交代码的时候，就会通不过：

sourceTree

如果你使用的 sourceTree 作为 git 的提交工具，你可能会发现在命令行中是可以出现错误的，但是 sourceTree 有的时候不灵了。

git hooks 在 sourceTree 有的时候会不灵，其实这不是 husky 的问题，大家可以看这篇文章：Git hooks doesn't work on Source Tree，其实就是环境变量没有添加的原因

我们可以看一下 .git/husky.sh 文件，它是根据 npx 去跑相应的命令的，在 sourceTree 需要在 .git/husky.sh 的头部加上相应的环境参数，才能让 husky 正常运作：

+ # $PATH是已有目录
+ PATH=$PATH:/usr/local/bin:/usr/local

这个时候在 sourceTree 上提交钩子就会生效了。

其他工具

除了 validate-commit-msg，我们其实还可以使用 commitlint 来帮我们验证 commit 是否规范，笔者在这里就不细讲了。

 

Commitizen

如果你觉得自己写规范的 comment 信息太麻烦，那么你可以使用Commitizen ，这是一个是一个撰写合格 Commit message 的工具。

安装

npm install -g commitizen

然后，在项目目录里，运行下面的命令，使其支持 Angular 的 Commit message 格式。

commitizen init cz-conventional-changelog --save --save-exact

以后，凡是用到 git commit 命令，一律改为使用 git cz。这时，就会出现选项，用来生成符合格式的 Commit message。

如下图：

 

生成 changeLog

如果你的所有 Commit 都符合 Angular 格式，那么发布新版本时， Change log 就可以用脚本自动生成。我们可以借助 conventional-changelog 帮我们生成 Change log 的工具，运行下面的命令即可。

conventional-changelog -p
angular -i CHANGELOG.md -s -r 0

我们可以在 package.json 中配置相应的 scripts 命令：

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

在提交发布之前运行一下这个命令就 ok 了，下图是生成的 change log 文件的例子，大家可以试一试：

 

语义化规范

我们选择 semver 来做语义化规范，它是由 github 起草的。

它是为了解决软件管理领域中的 依赖地狱 这个问题，如果你的依赖越来越多，项目越来越大的时候，就很有可能面临版本控制被锁死的风险（必须对每一个依赖包改版才能完成某次升级）。

 

优势

  • 能避免出现循环依赖
  • 依赖冲突介绍

下图是 react 中的依赖关系，很清晰，没有循环依赖：

 

规范格式

主版本号 MAJOR、次版本号 MINOR、修订号 PATCH，版本号递增规则如下：

  • 主版本号：当你做了不兼容的 API 修改，
  • 次版本号：当你做了向下兼容的功能性新增，
  • 修订号：当你做了向下兼容的问题修正。

先行版本号

当要发布 大版本 或者 核心的Feature 时，但是又不能保证这个版本的功能 100% 正常。这个时候就需要通过发布 先行版本。

先行版本号可以作为发布正式版之前的版本，格式是在修订版本号后面加上一个连接号**(-)，再加上一连串以点(.)** 分割的标识符，标识符可以由英文、数字和连接号 ([0-9A-Za-z-]) 组成。

  • alpha：是内部测试版，一般不向外部发布，会有很多 Bug。一般只有测试人员使用。

  • beta：也是测试版（公测，或者灰度版本），这个阶段的版本会一直加入新的功能。在 Alpha 版之后推出

  • rc：全称 Release Candidate， 系统平台上就是发行候选版本。RC 版不会再加入新的功能了，主要着重于除错。相当于 git 中的 release 版本。

1.0.0-alpha
1.0.0-alpha.1
1.0.0-0.3.7
1.0.0-x.7.z.92

 

实际案例

Vue 的版本

如下图所示：

React 版本案例

react 版本的一些注意点，为了能让开发人员更容易地测试 React 的预览版，官方使用了三个独立的发布通道来正式确定 React 的流程。

  • Latest 是稳定的，semver React 发布的通道。这是你从 npm 安装 React 时得到的，也是你今天已经使用的通道。对于所有面向用户的 React 应用程序，请使用此通道
  • Next跟踪 React 源代码库的 master 分支，下一个次要 semver 版本的候选版本，用于 React 和第三方项目之间的集成测试。
  • Experimental包括实验性 API 和在稳定版本中不可用的特性。这些特性也会跟踪 master 分支，但会打开附加特性的标记。使用此通道来试用即将发布的特性。

其中所有的版本都会发布到 npm，但只有最新的版本使用了语义版本。预览版（Next 和 Experimental 通道的版本）是根据其内容的哈希值生成的版本，例如 0.0.0-1022ee0ec 用于 Next 版本，0.0.0-experimental-1022ee0ec 用于 Experimental 版本。

更多 react 版本介绍大家可以参考：为 React 预览版的未来做准备

相似点

  • 软件的版本通常由三位组成，形如: X.Y.Z
  • 版本是严格递增的，在 vue 中是：3.0.0 -> 2.6.11 -> 2.6.10
  • 在发布重要版本时，可以发布 alpha，rc 等先行版本，react 比较特别在 16.6 之后增加了预览版。
  • alpha 和 rc 等修饰版本的关键字后面可以带上次数和 meta 信息

 

定义依赖版本号

在 npm 的依赖的规则中，还有 ~、>、<、=、>=、<=、-、||、x、X、* 等符号；当使用 npm install XX 时，被安装的依赖的版本号前会默认加上 ^ 符号。

  • ^ ：表示同一主版本号中，不小于指定版本号的版本号
`^2.2.1` 对应主版本号为 2，不小于 `2.2.1` 的版本号，比如 `2.2.1`、`2.2.2`、`2.3.0` ,
// 主版本号固定
// 当该依赖有最新版本时(eg:2.3.3)，npm install 会安装最新的依赖
  • ~ ：表示同一主版本号和次版本号中，不小于指定版本号的版本号
 `~2.2.1` 对应主版本号为 2，次版本号为 2，不小于 `2.2.1` 的版本号，比如 `2.2.1、2.2.2`，主版本号和次版本号固定
  • >、<、=、>=、<=、-：用来指定一个版本号范围
 `>2.1`
 `1.0.0 - 1.2.0`
// 注意使用 `-` 的时候，必须两边都有空格。
  • ||：表示或
 `^2 <2.2 || > 2.3`
  • x、X、*：表示通配符
 `*` 对应所有版本号
 `3.x` 对应所有主版本号为 3 的版本号

 

总结

今天这一节主要讲了 git commit 提交规范和 semver 语义化规范，当大家以后想要做一个项目，放到社区里里面给大家用的时候，这个会很有帮助。

 

相关链接

 

示例代码

示例代码可以看这里：