如何写好Change Log---调研分享

1.背景
当今软件开发往往是一个协作项目，需要多人参与。当项目步入正轨后，后续的开发人员经常需要提交一些代码去增加新的功能（feature）或者修复Bug。随着项目不断往后进行开发迭代，内容也会不断变化，我们对于项目里面的改动逐渐淡忘，这时候就需要项目保持更新日志（Change Log）来协调大家处于同一个步伐。
2.现状
目前很多公司开发项目都没有遵循一个很好的规范，不同开发人员开发完一部分项目后提交代码，往往会按照自己的风格定义自己的commit message，提交比较随意如下图这样，让人难以理解。当代码出现Bug时，也不清楚要回滚到哪个版本。

对此，有相关组织提出要标注化提交commit message的方案。其中Keep a Change Log[1] 和 AngularJS[2]都使用了各自的规范，其中AngularJS的规范是由谷歌推出的一套消息规范提交标准，是目前使用最为广泛的写法。因此本次分享着重介绍AngularJS的消息提交规范。使用AngularJS的提交规范后commit消息如下图所示。

3.目标

a. 在浏览的时候可以提供更好的历史信息

如通过下面这条命令可以显示上次发布后的变动，只看每次commit的行首就可以知道提交目的
git log HEAD --pretty=format:%s
在这里插入图片描述

b. 允许通过命令过滤掉某些提交信息

git log HEAD --grep feat ----查看新增加的功能:
在这里插入图片描述
git log HEAD --grep fix ----查看修复的bug:

c.允许通过脚本自动生成日志

在这里插入图片描述

4.提交信息（commit message）的格式

<type>(<scope>): <subject>     ---Header部分
<BLANK LINE>                 ---空一行
<body>
<BLANK LINE>                 ---空一行
<footer>

<type>(必填):

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

<scope>(可选):

所修改工程的范围，可以自行指定（当没用合适的范围时用*表示）。

<subject>(必填):

一条简短的标题，突出提交的内容，英文用一般现在时，首字母不大写，末尾不要标点。

扫描二维码关注公众号，回复： 12238790 查看本文章

<body>(可选)

描述具体的修改内容，英文用一般现在时，如

修改内容1
修改内容2
修改内容3

<footer>(可选)

适用于两种情况:
a. 不兼容变动

如果当前代码与上一个版本不兼容，则 Footer 部分以BREAKING CHANGE开头，后面是对变动的描述、以及变动理由和迁移方法。

BREAKING CHANGE: isolate scope bindings definition has changed.

To migrate the code follow the example below:

Before:

scope: {
    
    
  myAttr: 'attribute',
}

After:

scope: {
    
    
  myAttr: '@',
}

The removed `inject` wasn't generaly useful for directives so there should be no code using it.

b. 关闭Issue

如：

Closes#123

或：

Closes #123, #234, #345

<BLANK LINE>
空一行

注：
1.为了避免阅读的时候遇到换行的情况，每行一般不超过100个字符；
2.Revert：还有一种特殊情况，如果当前 commit 用于撤销以前的 commit，则必须以revert:开头，后面跟着被撤销 Commit 的 Header。

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body部分的格式是固定的，必须写成This reverts commit <hash>.，其中的hash是被撤销 commit 的 SHA 标识符。

5.使用工具
5.1 Commitizen（ https://github.com/commitizen/cz-cli ）
Mac电脑需要先安装npm，

$ brew install npm
$ npm install -g commitizen
$ commitizen init cz-conventional-changelog --save-dev --save-exact

使用git cz 代替 git commit
在这里插入图片描述

5.2 validate-commit-msg( https://github.com/conventional-changelog-archived-repos/validate-commit-msg )

校验格式工具，安装命令

$ npm install --save-dev validate-commit-msg

可以通过编辑文件来配置校验规则
在这里插入图片描述

5.3 conventional-changelog（ https://github.com/conventional-changelog/conventional-changelog ）
运行命令

$ npm install -g conventional-changelog-cli

$ cd my-project

$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0

自动生成日志

在这里插入图片描述

5.4 IDEA插件 Git Commit Template
在这里插入图片描述

6.总结：

[1] https://keepachangelog.com/
[2] https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.uyo6cb12dt6w

如何写好Change Log---调研分享

猜你喜欢