优雅的提交你的Git Commit Message

j5land j5land 收录于 代码规范  Git规范
   约 2178 字  预计阅读 5 分钟 

背景

Git 每次提交代码，都要写 Commit message（提交说明），否则就不允许提交。

git commit -m "hello world"

上面代码的-m参数，就是用来指定 commit mesage 的。

如果一行不够，可以只执行git commit，就会跳出文本编辑器，让你写多行。

git commit

基本上，你写什么都行，但是，一般来说，commit message 应该清晰明了，说明本次提交的目的。

Commit message的重要性

合理的Commit消息对项目维护至关重要。通过 Commit 历史可以清晰地看到整个项目的变迁和进展情况。

常见的Commit消息方式如下:

  1. 提交类型:feat/fix/docs/style/refactor/test等
  • 主要type
    • feat: 增加新功能
    • fix: 修复bug
  • 特殊type
    • docs: 只改动了文档相关的内容
    • style: 不影响代码含义的改动，例如去掉空格、改变缩进、增删分号
    • build: 构造工具的或者外部依赖的改动，例如webpack，npm
    • refactor: 代码重构时使用
    • revert: 执行git revert打印的message
  • 暂不使用type
    • test: 添加测试或者修改现有测试
    • perf: 提高性能的改动
    • ci: 与CI（持续集成服务）有关的改动
    • chore: 不修改src或者test的其余修改，例如构建过程或辅助工具的变动
  1. 修改范围:模块或功能名称
  2. 主题:简短描述,不超过50个字符
  3. 内容:更详细的描述,可以分多行

Commit 规范的意义

使用统一的Commit规范可以使项目历史更清晰可读,也便于使用Git工具进行分析统计。常用的规范有:

  • Angular Convention
  • Conventional Commits

采用机器可读的规范化Commit信息,也可自动生成Change log。

总之,高质量的Commit信息是项目管理的重要一环。

Commit message 的格式

本文格式主要介绍Angular 规范，Angular的Commit规范主要定义了Commit信息的格式和各部分含义,主要目的是通过规范的Commit信息,使得代码Review和Release log生成变得更加清晰易读。

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

其中:

  • type: commit的类型,包括feat(新功能)、fix(修复bug)、docs(文档)、style(格式)、refactor(重构)、test(测试)等
  • scope: commit影响的范围,比如模块名、功能名等
  • subject: commit的简短描述,不超过50个字符
  • body: commit详细描述,可以分为多行
  • footer: 一些备注,比如BREAKING CHANGE、modified、closed等

针对你提供的日志,我们来举几个例子:

feat(新功能)

feat(encoder): 支持自定义日志格式

在logback.xml中添加了一个新的PatternLayoutEncoder，以允许自定义日志格式配置。这可以用于灵活地定义日志输出格式。

BREAKING_CHANGE：默认情况下，现在使用PatternLayoutEncoder而不是先前的LogstashEncoder。

fix(修复bug)

fix(file-appender): 修复空指针异常

修复使用FileAppender记录空内容日志事件时发生NullPointerException的问题。在Appender中添加适当的空值检查。

已修复#10。

refactory(重构)

refactor(module): 提取公共类到logging-common

将SharedConfiguration、ConfigurationLoader和其他常用帮助类移动到一个单独的“logging-common”模块中。这将减少重复。

修改了AppConfiguration和LogbackHelper以依赖于logging-common。

可以看出采用了统一的格式,并且从类型、范围及描述内容上都很清晰的表达了这次Commit的目的。

这种规范的 Commit 信息非常适合用于日志分析和 Release Notes 的生成。我觉得如果引入 Angular Commit 规范,可以大大提高你们项目的 Commit 信息质量。

Commit message 的实践

在一个大功能的开发过程中，代码提交的粒度和提交信息如何合理进行是非常重要的。建议如下:

  1. 频繁小步提交,而不是开发完再提交。大功能开发还是要按照一定逻辑拆分成多个小步骤,每个小步骤完成后就提交一次代码,而不是全部开发完再提交。这样可以让主分支代码频繁更新,方便跟踪进展和回滚。
  2. 每次提交的粒度要有合理大小。每次提交的代码变更量不宜太大或太小。如果变更量太大,从提交信息难以把握代码变化。太小则提交次数过多,增加维护成本。每次提交可围绕一个较小的逻辑实现,保证尽量独立稳定。
  3. 提交信息要清晰准确描述代码变更。按照Angular Convention格式,提交信息要概述此次提交的类型(feat、fix等)、范围和具体变更,另外补充详细描述和注释,方便review。
  4. 示例提交信息:
feat(payment): 添加 PayPal 支付网关

1.实现用于支付的 PayPal API
2.调用为 PayPal 生成随机数并捕获订单
3.添加 PayPalConfiguration 类

在结账流程中添加 PayPal 支付支持。此提交为用户添加了一个新的付款选项。
相关 Jira 票号：PAY-7。

refactor(checkout): 优化结账服务逻辑

1.将与购物车相关的方法移动到 CartService 中
2.通过分离服务并将流程拆分为单独步骤来优化结账流程
3.为了更好的清晰度重新命名和重构方法
此提交通过将与购物车有关的逻辑提取到单独的服务类中来改进结账代码。

无 API 更改。改进了维护性。

fix(payment): 修复信用卡支付中的空指针异常

1.在访问信用卡对象之前添加空值检查
2.在开始支付时处理空卡情况
3.修复 CreditCardPaymentService 中出现的空指针异常，该异常在有效负载中缺少信用卡对象时发生。

请参见错误报告 PAY-113。

可以看出每次提交仅包含相关且能独立工作的代码变更，且提交信息清晰描述了变更，便于跟踪和理解。

综上，对大功能采取先拆分后频繁小提交，并明确描述每次变更。

更新于 2021-05-20 
Git
返回 | 主页
0%