代码记录 on Jarao's Blog

约定式提交 Conventional Commits

Thu, 27 Jul 2023 11:12:44 +0800

前段时间在公司提交代码的时候，看到仓库密密麻麻格式不一的commit记录有点头疼🤣，去问了下同事发现这块好像大家普遍都不注重，因此专门做了下关于约定式提交的调查。

为什么要规范commit

代码的Git提交是每个项目必经且十分频繁的操作，一个大型的、长期的项目如果在没有commit规范的情况下进行迭代，在经由不同的时期、不同的团队迭代后，commit记录会出现五花八门的格式，一是每个人的信息格式不一致会导致查阅者获取关键信息的效率低，二是时间久了就会出现因commit消息不清晰导致无法有效追溯变更记录。

这种情况在开源社区更是常见，因此基本上所有大型的开源项目为了保证信息规整有效，都会设立对应项目的commit规范。这不仅对于获取commit有效信息有很大的帮助，同时会让一个开发者去注意思考每次commit的功能、特性划分的合理性，如果配合一定的工具，还能够简便的生成规范的release日志。

其实说白了主要目的就是：

规范代码commit的信息，提高获取关键信息的效率，减少因团队更迭后造成的信息出入
通过git工具，快速生成标准release日志
获得共识，对齐业界（好歹别太low对吧🤪）

业界调研

当前我所在的公司没有commit的明确规范标准，而业界当前大部分的commit规范是基于「Angular Commit Guidelines」，这是一个js的commit规范，但是由于其定义的严谨性和通用性而被大部分项目采纳。

实际上这块还涉及一个版本号管理规范「语义化版本 2.0.0 | Semantic Versioning」，起初也是前端为了管理包版本设计的）

项目	Blocky	React	高德地图	Bootstrap	nginx	electron	openwrt
公司（社区）	Google	Meta	阿里	Twitter	nginx	electron	openwrt/lede
commit规范	约定式提交（基于 Angular Commit Guidelines）	Angular Commit Guidelines	如何规范你的Git commit？（基于Angular Commit Guidelines）	tbaggery - A Note About Git Commit Messages	Contributing Changes (nginx.org)	约定式提交（基于 Angular Commit Guidelines）	[OpenWrt Wiki] Submitting patches
共性	1. 以commit类型为开头，例如feat，fix，build 2. 类型后紧跟描述信息 3. subject或description长度不是都限制，但一般不宜超过50~100，力求言简意赅 4. body、footer可选，可以没有 5. 不在末尾增加句号 6. 会根据项目特性进行适当调整

Angular Commit Guidelines文档介绍中提及了「Google Style Guides | styleguide」，其部分设计思路是遵循该文档。

约定式提交使用介绍

特点

约定式提交则在保留了Angular规范的基础上，进行了部分调整和优化，例如明确允许scope的内容可选填（实际上阿里的规范也有这个优化，业内社区也普遍没有要求scope内容）；在具有破坏性的commit上使用「!」标记（对标SemVer强调破坏性提交的特点）等，并且谷歌、electorn等公司、项目也有使用，也算是受到业界认可的规范标准。

当然还有最重要的一点是，他有专门的社区维护，文档十分的完善，基本我们可以做到开箱即用，并且社区也提供了一些自动化工具。

具体规范我就不过多介绍（因为官方文档真的很详细了），以下摘抄一部分官方文档，可以感受下。

官方文档

概述

约定式提交规范是一种基于提交信息的轻量级约定。它提供了一组简单规则来创建清晰的提交历史；这更有利于编写自动化工具。通过在提交信息中描述功能、修复和破坏性变更，使这种惯例与 SemVer 相互对应。

提交说明的结构如下所示：

<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

提交说明包含了下面的结构化元素，以向类库使用者表明其意图：

fix: 类型为 fix 的提交表示在代码库中修复了一个 bug（这和语义化版本中的 PATCH 相对应）。
feat: 类型为 feat 的提交表示在代码库中新增了一个功能（这和语义化版本中的 MINOR 相对应）。
BREAKING CHANGE: 在脚注中包含 BREAKING CHANGE: 或 <类型>(范围) 后面有一个 ! 的提交，表示引入了破坏性 API 变更（这和语义化版本中的 MAJOR 相对应）。破坏性变更可以是任意类型提交的一部分。
除 fix: 和 feat: 之外，也可以使用其它提交类型，例如 @commitlint/config-conventional（基于 Angular 约定）中推荐的 build:、chore:、 ci:、docs:、style:、refactor:、perf:、test:，等等。
脚注中除了 BREAKING CHANGE: ，其它条目应该采用类似 git trailer format 这样的惯例。

其它提交类型在约定式提交规范中并没有强制限制，并且在语义化版本中没有隐式影响（除非它们包含 BREAKING CHANGE）。可以为提交类型添加一个围在圆括号内的范围，以为其提供额外的上下文信息。例如 feat(parser): adds ability to parse arrays.。

示例

包含了描述并且脚注中有破坏性变更的提交说明

1
2
3

feat: allow provided config object to extend other configs

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

包含了 ! 字符以提醒注意破坏性变更的提交说明

`1`	`feat!: send an email to the customer when a product is shipped`

包含了范围和破坏性变更 ! 的提交說明

`1`	`feat(api)!: send an email to the customer when a product is shipped`

包含了 ! 和 BREAKING CHANGE 脚注的提交说明

1
2
3

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

不包含正文的提交说明

`1`	`docs: correct spelling of CHANGELOG`

包含范围的提交说明

`1`	`feat(lang): add polish language`

包含多行正文和多行脚注的提交说明

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

为什么使用约定式提交

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

根据commit生成release日志

既然commit有了固定的格式，那我们自然可以根据这个格式来生成标准的日志啦
由于公司项目不是前端项目，也不是新项目，实在没法使用社区里自带的日志生成工具，于是就自己写了段shell支持🫠

git log --pretty=format:"%s https://url/commit/%H" | \
sed '/'$(git show-ref --tags | grep "project/v" | awk 'END{print}' | awk '{print $1}')'/,$d' | \
grep -E "^(feat|fix|refactor|chore): " | \
grep -v Merge | awk -F': ' '{print "["$1"]",$2}' | \
sed 's:\[feat\]:\[feature\]:g' | sed 's:\[fix\]:\[bugfix\]:g'

已经分享给公司的同事，希望今后团队commit能有改善吧🤣

相关文档：

Go泛型学习笔记

Thu, 24 Mar 2022 21:04:21 +0800

封面PID=98135423

Go自从1.18开始正式支持了泛型，官方称其为Go开源发布之后最大的一次变更。
在出现泛型之前，Go传递不定参数的通用方法是传递接口，这次支持泛型无疑是对Go编码影响巨大的升级。

本文针对学习过程中的一些要点做初步记录。

泛型

Go支持了泛型，为其带来了三个新的特性：

Type parameters for function and types.

Defining interface types as sets of types, including types that don’t have methods.

Type inference, which permits omitting type arguments in many cases when calling a function.

简单来说，就是支持了函数、type关键字的类型参数，使用无方法接口实现类型集，函数调用泛型推理省略类型参数。

以下是参照Go的官方例子做的示例：

// 无方法接口实现类型集
type Number interface {
	int | float64
}
// 函数类型参数
func GMin[T Number](x, y T) T {
    if x < y {
        return x
    }
    return y
}

Hit:

类型参数用[]来进行定义，泛型标识符T。
Go的编译器会在替换泛型标识符后检查实际类型是否满足函数的类型约束条件。

// 这一步编译器会进行函数实例化，如果类型不满足函数内部约束条件（本例里是运算符 '<' ），则会报错
fmin := GMin[float64]   // float64在这就是实际指定的类型
m := fmin(2.71, 3.14)   // 实例化成功后可正常调用 
fmt.Println(m)          // 2.71

其中Go在进行编译时会进行类型推算（type inference），因此你也可以将你的函数写成：

1
2

m := GMin(2.71, 3.14)   // 不需要手动指定T的真实类型，Go自己推算
fmt.Println(m)          // 2.71

以上是一个简单的Go泛型函数调用，其中我们可以看到Go使用了接口关键字interface关键字来定义泛型的约束类型。接下来我们就说说为啥Go是用interface来定义泛型的约束类型集。

泛型约束集

接口定义了一系列方法，实现了这些方法的type可以表现成type->接口的一种映射关系；从另一个角度上来说，接口同样定义了一个实现了这些方法的type的集合，这个集合中的type都实现了接口的方法。因此我们反过来可以获得接口->type的映射关系

官方博客里的这张图片里展示了一个接口在被多个type实现时所具有的集合关系，其中每一个圈都是一个接口的方法集。可以看到，typeP、Q、R在实现了interface后，会在中心区域有一个“方法交集”。这个交集反过来定义了下图的类型集。

一般的接口是方法的接口，这里泛型的接口可以理解为类型的接口。

Go的泛型还支持指定某个Underlying Type，例如：

1
2
3

type Number interface {
	~int | float64
}

上述代码中，~int表示所有以int为Underlying Type的类型。

泛型的Core Type

需要注意的是Go的在使用内置函数的时候需要确定类型的Core Type，比如使用make、range等操作。如果你的泛型interface没有Core Type，你会看到类似如下报错

type NumberSlice interface {
	[]float64 | []int | []string
}

func test[T NumberSlice](num T) {
    // cannot range over num (variable of type T constrained by NumberSlice) (T has no core type)
	for _, v := range num {
        // do something
	}
}

这是因为Go定义类型接口的Core Type只在两种情况存在：

接口类型集存在统一的Underlying Type

接口类型集存在统一的管道，管道的类型、方向需一致

像上面的代码，NumberSlice由于不存在相同的Underlying Type，因此不具有Core Type，不能使用range关键字进行操作。不过我们可以通过调整泛型来实现相同的功能：

type Number interface {
	float64 | int
}

func test[T Number](num []T) {
	for _, v := range num {
		 // do something
	}
}

这样就可以正常的实现遍历泛型slice了。

相关文档：