导语:任何软件项目都是一个协作项目,它至少需要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文档内容,会在这个文件的最上面插入新生成的日志信息。

参考链接

开源信息

如何写好 Git commit messages的更多相关文章

  1. 如何写好git commit message

    1.触发事件 我有这样一个版本库,里面包含两个学习用的练习项目:BookStore(以下简称BS)和PictureFriend(以下简称PF) 我在更改PF以后,未进行提交,同时又到BS中优化了一下文 ...

  2. git commit -m与-am的区别

    前面的话 使用git commit -am是不是就可以完全不使用git add命令呢?不是 理论 要了解git commit -m与git commit -am的区别,首先要明白它们的定义 字面解释的 ...

  3. 从code review到Git commit log

    最近在读一本技术类的书:朱赟——<跃迁:从技术到管理的硅谷路径>,其中聊了很多很有趣的观点,比如:技术管理.技术实践.硅谷文化.个人成长等. 读到关于硅谷人如何做code review这一 ...

  4. Git commit 信息标准和丢弃必须要的commit

    /***************************************************************************** * Git commit 信息标准和丢弃必 ...

  5. 如何规范git commit提交

    相信很多人使用SVN.Git等版本控制工具时候都会觉得每次提交都要写一个注释有什么用啊?好麻烦,所以我每次都是随便写个数字就提交了,但是慢慢的我就发现了,如果项目长期维护或者修改很久之前的项目,没有一 ...

  6. git commit guidelines

    git-commit-guidelines AngularJS Development Setup Running Tests Coding Rules Commit Message Guidelin ...

  7. 写一个体验良好的git commit

    一直在使用git也看过格式各样commit log , review 代码时最刺激的是看到这类 "." 应付差事,还有 "fix bug","fix& ...

  8. 我是怎么写 Git Commit message 的?

    目录 作用 用的什么规范? type scope subject body footer 参考文章 用的什么辅助工具? 作用 编写格式化的 commit message 能够大大提高代码的维护效率. ...

  9. 规范git commit提交记录和版本发布记录

    在开发过程中我们一般都会用到git管理代码,在git commit提交代码时我们一般对git commit message随便写点简单的描述,可是随着项目参与人数的增多,发现提交的commit记录越来 ...

随机推荐

  1. 打包程序时的证书问题(上传APP就出现Missing iOS Distribution signing indetity for)

    现象: 解决办法: 1.删除本地钥匙串中的这个文件,注意“系统”中的同名文件也必须删除 2.进入http://www.apple.com/certificateauthority/ 下载新的(WWDR ...

  2. 代码中动态改变布局属性RelativeLayout.LayoutParams.addRule()

    我们知道,在 RelativeLayout 布局中有很多特殊的属性,通常在载入布局之前,在相关的xml文件中进行静态设置即可. 但是,在有些情况下,我们需要动态设置布局的属性,在不同的条件下设置不同的 ...

  3. 【Xilinx-VDMA模块学习】-00-开始

    最近在做XILINX图像相关的逻辑,需要用到VDMA模块,最后算是把这个模块摸得比较透了. 先在这里记一下,之后有空了总结一下.包括VDMA在Vivado中的GUI配置和软件驱动的详细理解.

  4. 【转】sql语句的优化分析

    开门见山,问题所在 sql语句性能达不到你的要求,执行效率让你忍无可忍,一般会时下面几种情况. 网速不给力,不稳定. 服务器内存不够,或者SQL 被分配的内存不够. sql语句设计不合理 没有相应的索 ...

  5. 利用JS做到隐藏div和显示div

    div的visibility可以控制div的显示和隐藏,但是隐藏后页面显示空白 style="visibility: none;" document.getElementById( ...

  6. Delphi在Vasta/win 7下通过UAC控制

    在Windows编程时,为了兼容Win7与XP,许多需要底层权限的程序需要通过UAC验证,这是微软出的一个很恶心的东西……还不如Ubuntu那种Root机制呢……但是有困难我们就要克服-现在有一种方式 ...

  7. --@angularJS--指令与控制器之间的交互demo

    1.index.html: <!DOCTYPE HTML><html ng-app="app"><head>    <title>c ...

  8. magento1.x 运行在 php7 优惠券的问题

    diff --git app/code/core/Mage/Sales/etc/config.xml index 5bb43d7..7db62ca 100644 --- app/code/core/M ...

  9. Java线程:同步

    一 同步的概念 线程的同步是为了防止多个线程访问一个数据对象时,对数据造成的破坏. 例如:两个线程ThreadA.ThreadB都操作同一个对象Foo对象,并修改Foo对象上的数据. MyRunnab ...

  10. JSP 初始化参数

    JSP 初始化参数: tomcat启动的时候就会执行那个函数: xml: <?xml version="1.0" encoding="UTF-8"?> ...