中文 Git Commit Message 风格指导

在团队合作项目中,不好好写 Git Commit Message 是会被工友竖中指的 (┛`д´)!每个人写代码的习惯多多少少都有一些差别,对于一个人来讲非常合理的操作,在另外一个人看来或许就会很魔幻。这个时候如果有一份清晰完整的提交记录,那么后续的代码维护着就可以更加清楚的知道前任代码编写者的意图。因此撰写清晰明确的 Commit Message 是一件能够防止工友心跳加速和办公室暴力的事情。

考虑到很多工作团队使用的是全中文的工作环境,目前也很少看到中文的 Commit Message 书写指南,所以姑且参考各种英文版本的指南,扒一份中文版的给自己用。如果你觉得这份文档写的不错,也欢迎在团队中推广这份指南。

Commit Message 标题

一份 Commit 的标题应当包含这几个部分:类别、上下文、兼容性警告、提交意图,它应当遵循如下格式:

1
2
<类别>(<上下文>):<兼容性警告><提交意图>
^ 全角括号 ^全角冒号 ^不加句号

比如:

1
2
重构(首页):⚠调整视频卡片组件 props API
修复(播放列表):查询构建器传入的 `number` 数据类型定义错误

类别

类别以最粗浅的方式描述了本次更新所做的事情,您仅应当使用如下关键字作为 Commit 标题的类别:

  • 功能(feat): 实现了一个新的功能,但不包含构建脚本和自动化测试;
  • 修复(fix): 修复了一处功能异常,但不包含构建脚本和自动化测试;
  • 文档(docs): 任何文档的新增、删除与修改;
  • 格式(style): 不对代码实际内容产生影响的代码格式调整工作,如删除或补全分号、缩进调整;
  • 重构(refactor): 对已有的代码进行重构,包括对变量的重命名;
  • 测试(test): 增加新的测试,修改已有测试,重构测试,不涉及业务逻辑代码变化;
  • 杂务(chore): 依赖升级等不适用上述关键字的内容,且不涉及主要代码变动;
  • 内容(pub): 适用于静态博客仓库以及内容代码混在一起的孽障仓库,增加或修改了内容都应当使用此关键字。

上下文

该部分描述您究竟对于哪部分逻辑做了修改,不应超过五个汉字,如果不好描述也可掠过此条目。下面是一些例子:

  • 初始化
  • 配置
  • Web 服务器
  • 代理
  • 首页
  • 用户中心
  • ……

兼容性警告

如果本次改动涉及了 API 变化,应当在 Commit Message 的标题中明确的标明,请将「⚠」符号置于提交意图前。

提交意图

提交意图以简短的方式描述了本次修改的主要内容,这一部分应当遵循如下几个基本准则:

  • 不应超过三十个汉字;
  • 标题末尾不加句号,如果需要使用英文,那么应当保留首字母大写;
  • 仅描述「为什么」要做这件事,而不要包含「如何」做这件事;
  • 如果问题较难描述,那么应当起草一份 issue 详细描述该问题,或者找到已经对这一问题有较好描述的 issue,并在标题中以 「修复 #1234」的方式引用到这一 issue。

下面列举一些例子:

很好:

  • 重构导航栏以增加代码可读性;
  • 更新光效组件文档,增加 --reveal-background 属性;
  • 删除废弃的函数;
  • 发布 v1.1.0 版本。

不好:

  • cargo fix 修复 bug;
  • 修改中间件的行为;

你会被打:

  • 修改1
  • 更新代码
  • 加几个新函数
  • 42
  • 周五约饭吗?

Gitmoji?

也有一个叫做 Gitmoji 的规范,通过在 Commit 标题的最开始加一个 Emoji 来表明此次修改的意图,不过我个人觉得这玩意挺扯的……如果你感兴趣可以看看:

https://gitmoji.carloscuesta.me/

Commit Message 正文

撰写 Commit Message 正文的目的是告诉读者你修改了什么、你为什么要修改。这样阅读修改记录的人可以在无需翻阅全部代码修改历史,就能够了解你做了什么。这一部分是可选的,如果标题已经可以完整描述此次修改,那么可以不撰写正文。如果需要撰写正文,请遵循如下准则:

  • 30个全角字符或60个半角字母为一行;
  • 假设阅读此正文的并不知道你在解决的问题;
  • 假设阅读修改记录的人不能通过你的代码本身就了解你是如何解决问题的;
  • 把最重要的信息放在最上面。

正文的页脚

如果本次修改解决了一个或多个 issue,那么您应当在页脚处明确写出,issue 编号应依照从小到大的顺序进行排列。页脚与正文应当使用且仅使用一个空行进行分割,下面是一个范例:

1
2

解决了: #2 #123 #621

如果本次修改影响到了 API 的兼容性,应当随后明确写出,并明确描述修改的详情,比如:

1
2
3
**兼容性警告:**

`NagivateButton` 的 `href` 属性被修改为 `to` 属性,以便与 `react-router-dom` 的 `Link` 组件保持 API 一致。

参考

Comments