如何写好 Git commit messages

作者:程柳锋

导语

任何软件项目都是一个协作项目,它至少需要2个开发人员参与,当原始的开发人员将项目开发几个星期或者几个月之后,项目步入正规。不过他们或者后续的开发人员仍然需要经常提交一些代码去修复bug或者实现新的feature。我们经常有这种感受:当一个项目时间过了很久之后,我们对于项目里面的文件和函数功能渐渐淡忘,重新去阅读熟悉这部分代码是很浪费时间并且恼人的一件事。但是这也没法完全避免,我们可以使用一些技巧尽可能减少重新熟悉代码的时间。commit messages可以满足需要,它也反映了一个开发人员是否是良好的协作者。

编写良好的Commit messages可以达到3个重要的目的:

  • 加快review的流程
  • 帮助我们编写良好的版本发布日志
  • 让之后的维护者了解代码里出现特定变化和feature被添加的原因

先来看看一个比较好的例子,感受一下:

下面谈谈,如何让项目里面的Commit messages步入规范化,流程化。

Commit messages的基本语法

<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Type表示提交类别,Subject表示标题行, Body表示主体描述内容。

Type的类别说明:

  • feat: 添加新特性
  • fix: 修复bug
  • docs: 仅仅修改了文档
  • style: 仅仅修改了空格、格式缩进、都好等等,不改变代码逻辑
  • refactor: 代码重构,没有加新功能或者修复bug
  • perf: 增加代码进行性能测试
  • test: 增加测试用例
  • chore: 改变构建流程、或者增加依赖库、工具等

Commit messages格式要求

# 标题行:50个字符以内,描述主要变更内容
#
# 主体内容:更详细的说明文本,建议72个字符以内。 需要描述的信息包括:
#
# * 为什么这个变更是必须的? 它可能是用来修复一个bug,增加一个feature,提升性能、可靠性、稳定性等等
# * 他如何解决这个问题? 具体描述解决问题的步骤
# * 是否存在副作用、风险? 
#
# 如果需要的化可以添加一个链接到issue地址或者其它文档

这3个问题给代码的变更建立了良好的上下文,可以让其他的代码review人员或者项目成员直观的判断修改点是否正确。一条良好的commit message也可以让维护者知道这个patch是否适合发布到稳定的版本中去。

如果一个patch没有回答上面的这几个问题,那么它是无意义的。它会给review的人员造成负担,让他们花费大量时间去评审讨论这个patch的作用和意义。更糟糕的是,如果一个项目实施SCM纪律,则这个patch会被拒绝掉,然后开发人员需要花费时间重新编写一个新的patch。重新编写一个复杂的patch代价是巨大的,而把commit message写好只会花费几分钟。

Commit messages书写建议

  • 尽可能多的提交,单个Commit messages包含的内容不要过多;
  • 标题行以Fix, Add, Change, Delete开始,采用命令式的模式。不要使用Fixed, Added, Changed等等;
  • 始终让第二行是空白,不写任何内容;
  • 主体内容注意换行,避免在gitk里面滚动条水平滑动;
  • 永远不在 git commit 上增加 -m 或 --message= 参数,提交的时候git commit即可;
  • 如果你是vim用户,将下面这行代码加入到~/.vimrc。这会帮助你检查拼写和自动换行。 autocmd Filetype gitcommit setlocal spell textwidth=72

使用Commitizen工具

Commitizen可以让你的commit message更加规范统一,适合项目团队使用,使用也很简单,使用npm安装后,提交代码的时候使用git cz去替代以前的git commit命令即可。

安装commitizen:

$ npm install -g commitizen

使用截图:

自动生成Change log

conventional-changelog是用来从git的元数据中生成 Change log文档的工具,只要你提交的格式满足它定义的标准,此处以angular标准为例子。使用它生成的Change log包含以下三个部分:

  • Bug Fixes Bug修复的信息
  • Features 增加的特性
  • BREAKING CHANGES 重大变更

可以参考它生成的文档CHANGELOG.md,使用如下:

$ npm install -g conventional-changelog-cli
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -s

这不会覆盖你之前的CHANGE.md文档内容,会在这个文件的最上面插入新生成的日志信息。

参考链接

原文链接:http://ivweb.io/topic/58abda9d2117ae2f4995b4a8

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

编辑于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏逸鹏说道

专业上的常用的工具和类库集

Visual Studio 2013 扩展 CodeMaid: 可快速整理代码文件,清理不必要的代码和杂乱的格式。并在开发时实时提供代码复杂度的报告,以便帮助开...

2879
来自专栏aCloudDeveloper

python学习笔记一

之前看过一本100多页的《python简明教程》,都是些非常简单的语法,现在到真正用的时候根本无从下手,所以,重新捧起一本《python学习手册》,1000多页...

1717
来自专栏跟着阿笨一起玩NET

WEB免费打印控件推荐

要么购买成熟的打印控件,如果是大项目可以考虑,但如果项目只有几K到1、2W之间,这就麻烦了。

3431
来自专栏大数据挖掘DT机器学习

Python爬虫框架Scrapy实战之定向批量获取职位招聘信息

所谓网络爬虫,就是一个在网上到处或定向抓取数据的程序,当然,这种说法不够专业,更专业的描述就是,抓取特定网站网页的HTML数据。不过由于一个网站的网页很多,而...

3704
来自专栏社区的朋友们

Node.js 在 CLI 下的工程化体系实践

如果想要对每个项目进行一些规范的约束比如 Git 提交规范、Javascript规范简直难于登天。所有的这些,只因为缺少一个好用的工程化工具。从项目创建、开发、...

1761
来自专栏LiveEdu在线科技教育平台

10最好用的Node.js工具、插件和资料库

每一个称职的程序员都应该拥有一套极好的工具来提高自己的工作效率。在Livecoding.tv 上,那里的程序员分享了10个他们认为是最好用的工具、插件和资料库。...

27611
来自专栏java一日一条

Spring 测试:其实很简单

在过去的职业生涯里,我经常发现有些人不写测试代码,而他们声称不写的理由是无法轻易地写出覆盖多个不同模块的测试用例。好吧,我相信他们中的大部分要么是缺乏一些比较易...

932
来自专栏程序人生

深入了解IAM和访问控制

本文为InfoQ中文站特供稿件,首发地址为:http://www.infoq.com/cn/articles/aws-iam-dive-in。 访问控制,换句话...

3937
来自专栏向治洪

携程Android App的插件化和动态加载框架

携程Android App的插件化和动态加载框架已上线半年,经历了初期的探索和持续的打磨优化,新框架和工程配置经受住了生产实践的考验。本文将详细介绍Andro...

16710
来自专栏Android干货园

Reading:一款不错的Material Desgin风格的Kotlin版本的开源APP

版权声明:本文为博主原创文章,转载请标明出处。 https://blog.csdn.net/lyhhj/article/details/81...

743

扫码关注云+社区