Git新手教程-日志提交规范(五)补充

前言

如果大家学习了之前的文章 Git新手教程-向仓库中添加commit(五),我相信大家肯定还会为如何提交一个比较规范的 commit 信息而烦恼,虽然我们在上面的文章中介绍了两篇相关的文章:

我相信大家肯定还是会疑惑。这里就以我之前理解的 commit 规范为列子。希望起到一个抛砖引玉的作用。毕竟 commit 信息只是人为规范。不同公司,不同项目,不同人有着自己的见解。因为作者本身是一名爱岗敬业的 Android 程序员,可能提交日志相对于倾向于移动端,所以如果大家有更好的提交日志分享。这里非常欢迎在评论中看到你的回答~

反面例子

在了解我的提交规范之前,我们来看一些反面的 commit 信息:

  • 修改登录界面的Bug
  • 修改空指针异常
  • 增加提示
  • 代码优化
  • 调整UI

从上述 commit 信息中,我相信大家已经看出一些问题,就是这些 commit 消息意图都指代不明。我们根本能从这些 commit 中知道,到底是为了解决什么问题而提交的。

就拿 "修改登录界面的Bug” 来说,到底登录界面有什么 Bug ?就不能写清楚吗? "修改空指针异常”,哪个界面的空指针?导致空指针的原因,又是什么呢?

这个时候你可能会说:”我们可以查看 commit 对应所提交的文件, 你看修改的文件不就知道我干了什么吗?” 对!好像从代码中我能知道你干了什么,但是我懒啊,我不想看你写的代码,我只想知道你提交这个 commit 的起因及解决方式,对于你的代码我不想关心。

当然这并不是懒不懒的原因,一个好的 commit 就像指路牌一样,总能简单明确的告诉我们明确的信息。特别是在项目后期维护与迭代中,我们能也根据这些 commit 快速锁定问题。总之一个良好的 commit 有着不容小觑的作用,那接下来看看关于我的日志提交规范吧。

关于我的日志提交规范

整个信息结构由两个不同的部分构成,这些部分由空行分割:标题、可选的消息体。

1
2
3
标题

消息体

具体的结构如下所示:

1
2
3
4
5
6
7
8
9
类型:【项目组名称/简称】【Bug/需求Id】【有无风险】【有无依赖】【需求/Bug/更改描述】

- 分析:
- 风险:
- 解决方案:
- 测试建议:
- 适用范围:
- 测试机型:
- 自测结果:

标题

标题一般情况下,都不超过 50 个字符,末尾不加句号。如果50个字符,还不能很清楚的描述你这次的 commit 。那么你可以在消息体中具体描述。接下来我们就分别介绍标题中涉及到的选项。

类型(必填)

类型位于在标题内,有以下几种可能:

  • Feat(feature):新功能
  • Fix:bug 修复
  • Docs:文档修改,注释更改
  • Style:修改代码格式、补充分号等
  • Refactor:代码重构
  • Test:测试添加、测试重构等,代码无变动
  • Chore:构建任务更新,程序包管理器配置等,代码无变动。
  • Revert:恢复先前的提交

添加类型主要的目的,不仅是为了帮助自己或其他人理解对应 commit 主要干了什么,还可以筛选同类型的提交。比如我们可以筛选出所有的feat(新功能) ,那么在发布新版本的时候,我们能更好的书写版本发布日志。

项目组名称/简称(非必填)

填写项目组名称或者简称,但是一般建议简称。这样我们就能迅速找到该项目组提交的代码。代码如果出现了问题,我们也能快速定位到哪个组该背锅,你说是不?

Bug/需求 Id(必填)

Bug/需求Id 需要对应你自己的公司项目的管理工具,如 JIRAIcafeTeambition 等,这里将 Id 放在标题内,也是考虑到起到一个快速定位的作用,放在标题处显眼!!!

有无风险(非必填)

在实际的项目开发中,往往会涉及到系统版本兼容问题、数据库迁移问题、特定版本API使用问题、项目新老版本适配问题等其他风险。在项目开发中,我们需要将这些风险明确指出。 如果你这次提交内容中包含一些风险因数,那么这里我们就可以添加【有风险】,具体什么风险,我们可以在消息体中的风险模块中具体描述。

有无依赖(非必填)

这里有无依赖是指的是否依赖其他模块,如果公司的项目很大,一般都会涉及到多模块,不同模块之间肯定会有依赖关系。这里举一个简单的例子,假如我们开发的是一个商场项目,现在我们是基础业务组,现在有一个需求#331,需要让我们实现点击某个商品,完成购物,那么我们肯定会涉及到用户支付,而支付又是支付组在负责。那么在进行 commit 提交时,我们就可以添加【依赖支付模块】,这样做不仅可以让我们的测试工程师清晰的知道需求所包含的模块。也能在功能出现问题的时候,能够找准方向,对症下药。

需求/Bug/更改描述(必填)

在标题处,通过对需求、Bug、更改的简短的描述,也能快速的让其他人知道我们这个提交到底是做什么的。一般情况下,描述以动词开头,比如新增某个功能、移除了什么、更新了什么、重命名了什么、移动了什么等等。总之简短扼要就行了,如果你觉得简短的语句,并不能很好的概况所需要解决的问题。那么你可以在消息体中在进行详细的描述。

消息体(选填)

消息体,可以看做对标题的细致描述。并不是所有的提交信息都复杂到需要消息主体,因此这是选填内容,仅在提交信息需要一定的解释和语境时使用。消息体主要用于解释与完善提交任务的内容和原因。接下来我们就来分别讲解消息体中包含的其他选项。

分析(选填)

分析模块:主要对需求的场景分析Bug出现的原因进行介绍。这里分析的作用非常重要。不仅能验证开发人员对功能或 Bug 的理解程度,还能减少公司新来的小伙伴阅读代码,了解业务的时间。

风险(选填)

风险模块:是对标题中的【有风险】进行详细的阐述。具体怎么描述,根据自己的实际项目而定。

解决方案 (选填)

解决方案模块:该模块主要针对于性能优化Bug修复。主要用于解释所解决的问题的方式方法。

测试建议 (选填)

测试建议模块:该模块主要针对于新功能开发Bug修复。在该模块中,我们可以详细说明,有哪些界面,哪些功能需要测试。这对于采用自动化打包工具(比如 Jenkins)的 团队特别有用,因为我们的测试小伙伴可以在使用自动化打包工具打包时,就能看见你提交的 commit ,那么根据你提供的测试建议,他们也能知道到测试过程中需要着重测试的地方以及需要注意的地方。

适用范围 (选填)

适用范围模块:该模块主要包含的内容 取决于 commit 的内容是针对某一系统版本,针对于特定设备,还是包含所有。这里可以根据自身的提交来填写。

测试机型(选填)

因为作者我是一名 Android 程序员,所以这里单独抽出了测试机型,也是合情合理的。

测试机型模块:该模块主要包含内容为你当前项目所运行的设备机型。当然因为 Android 的碎片化,在实际的项目开发中,我们可能会考虑不同厂商下的不同手机型号下的不同系统版本适配的问题。所以这里的机型,并不是唯一值,还是要根据自身的提交来填写。

(PS:Android 程序员就是这么辛苦,为什么工资没有 IOS 的高,不开心。)

自测结果

自测结果模块:完成新功能或修改 Bug 后,填写自测结果。不仅是对我们自己工作成果的验收,还能减少因为代码的问题而增加的返工次数,虽然我们不能保证自己测试后,就没有任何的问题了,但是至少我们的态度是端正的对吧~

例子展示

了解了规范之后,我们来看看常用的 commit 书写。

功能开发

对于功能开发,我们一般需要标题与消息体。具体例子如下所示:

1
2
3
4
5
6
7
8
9
Feat:【CT】【#1345】【无风险】【无依赖】【优化了优惠券的展示方式】

- 分析:顾客账户的优惠券太多,如果按照原来的一个个展示,显示比较混乱。所以需要将同类型的劵合并展示。
- 风险:无
- 解决方案:将同类型的优惠券合并展示
- 测试建议:测试优惠券展示界面
- 适用范围:所有版本
- 测试机型:oppo、miui、huawei
- 自测结果:通过

在该 commit 中,标题中的数据如下:

  • Feat:功能类型
  • 【CT】:为项目组名称/简称
  • 【#1345】:为需求ID
  • 【无风险】:有无风险、无则显示为无
  • 【无依赖】:有无依赖,无则显示为无
  • 【优惠券展示优化】:功能的简要描述,以动词开头

消息体中的数据,比较明显,这里大家可以自己的项目需求来填写。

Bug 修改

Bug 修改的 commit 信息 与功能基本开发一样,唯一的区别就是 commit 的 类型为 Fix。具体例子如下

1
2
3
4
5
6
7
8
9
Fix:【FS】【#123】【无风险】【无依赖】【修改登录界面密码框输入空字符串导致的程序崩溃】

- 分析:因为在输入密码时,没有对数据进行判空处理,所以会导致空指针异常。
- 风险:无
- 解决方案:对密码字符串进行判空处理,如果为空则提示用户输入密码。
- 测试建议:对bug进行回顾测试
- 适用范围:所有版本
- 测试机型:oppo、miui、huawei
- 自测结果:通过

文档与样式修改

因为文档的编写与文档的样式修改并不会影响主体的代码,所以我们不用像新功能开发与bug修改那样书写很完整的 commit 信息,只需要简明扼要的描述我们修改的内容就可以了。

文档修改:

1
Docs: 修改了 MainActiviy 类中的方法注释

或者

1
Docs: 添加了使用指南的文档

格式样式修改:

1
Style:修改了 MainActiviy 类中的格式

其他注意事项

在进行 commit 时,我们仍然需要注意以下事项:

  • 我们需要保证对项目的 commit 是针对新增某一个功能或修复某一个Bug 所作的提交。而不是该提交中包含对其他功能模块的修改。
  • 我们尽量创建短小而明确的 commit ,什么是短小而明确的 commit 呢?其实很简单,我们的 commit 所涉及的文件最好不要超过10多个文件或数百行的代码更改。我们的 commit 要有针对性。

题外话

虽然了解一个项目的最好的方式就是 read the fucking source code,但是如果项目本身有着良好的 commit ,总会给我们带来事半功倍的效果对吧。从一些小事严格要求自己,我相信以后总会为我们带来一些特别的惊喜~~