Commit Message & Change Log

每一次commit是阶段性的Ending,应记录着这一阶段所完成的事以及关注点,尽可能详细具体。

Angular Commit Message

注:如果可以的话,提交信息应通过 E-mail 发送给工程师和其它关注项目的人。

Commit Message格式化

每个commit message应该包含一个header、一个body和一个footer;header有一个特殊的格式,包含type(类型)、scope(作用域)和subject(主题):

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

header是必须有的,但是其scope是可选的。

注意:commit message的任何行不能超过100个字符,方便阅读。
样例:

docs(changelog): update change log to beta.5

上图 Angular Commit Message 就是很好的范例。

Type

提交类型,必须是下列之一:

  • build:影响构建系统或外部依赖的改变
  • ci:改变CI配置文件和脚本
  • docs:只改变文档
  • feat:一个新功能
  • fix:一个bug fix
  • perf:代码更改,提高了性能
  • refactor:代码重构
  • style:不影响代码含义,只是代码风格的改变
  • test:添加缺失的测试或修正现有的测试
  • wip:移除文件或者代码

Scope

scope应该是被影响的包的名称,这样能方便阅读根据提交信息生成的更新日志。
比如,工具类的包名为Tools,本次提交为工具类里的修改,那么scope就为Tools:

feat(Tools): add a data utils

具体的scope根据项目中各模块的包名而定。

subject

subject是 commit 目的的简短描述:

  • 以动词开头,使用第一人称现在时,比如change,而不是changed或changes
  • 第一个字母小写
  • 结尾不加句号(.)

Body

Body 部分是对本次 commit 的详细描述,可以分成多行。
注意:

  • 使用第一人称现在时,比如使用change而不是changed或changes。
  • 应该说明代码变动的动机,以及与以前行为的对比。

Footer

Footer分两种情况:

  • 不兼容变动:如果当前代码与上一个版本不兼容,则 Footer 部分以BREAKING CHANGE开头,后面是对变动的描述、以及变动理由和迁移方法。
  • 关闭 Issue:如果当前 commit 针对某个issue,那么可以在 Footer 部分关闭这个 issue 。

Revert

还有一种特殊情况,如果当前 commit 用于撤销以前的 commit,则必须以revert:开头,后面跟着被撤销 Commit 的 Header。

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

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

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

NPM

npm是随同Node.js一起安装的包管理工具,后面介绍的工具Commitizenconventional-changelog都要使用npm来安装。

既然是Node.js的包管理工具,那么首先就要下载Node.js,通过Node.js下载地址下载安装Node.js。

然后安装npm:

curl -L https://www.npmjs.com/install.sh | sh 

Commitizen

Commitizen是一个格式化commit message的工具。

通过上面安装好的npm来安装:

npm install -g commitizen

而我们用的是Angular的commit message规范,那么就在我们项目的目录下输入以下命令:

commitizen init cz-conventional-changelog --save --save-exact

但是注意,因为commitizen工具是基于Node.js的,而我们iOS项目工程目录下是没有package.json文件,所以会报错:

Error: ENOENT: no such file or directory, open '/Users/***/package.json

关于这个问题,可以参考这个commitizen的issue:Usage in non-node projects?,对于非Node的项目,我们可先在我们项目中添加一个空的package.json文件,然后再输入命令:

npm init --yes

先初始化配置package.json文件,然后再输入命令:

commitizen init cz-conventional-changelog --save --save-exact

看到以下信息,且没有报错表示成功:

这样当我们提交的时候,就用git cz替换git commit命令,会出现提交类型的选择:


然后根据提示选择、输入就是了。

注意如果是第二次配置,需要用--force

commitizen init cz-conventional-changelog --save --force

生成CHANGELOG

conventional-changelog就是生成 Change log 的工具。

运行下列命令:

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

但是最后出现command not found,以为是conventional-changelog没有安装,通过命令:

npm ls -g -depth=0

打印出:

/usr/local/lib
├── commitizen@2.9.6
├── conventional-changelog@1.1.0
├── cz-conventional-changelog@2.0.0
└── npm@4.3.0

明明是有的,苦思不得其解,最后在这篇文章Git 提交记录和分支模型中发现Commitizen就依据conventional message,创建起一个生态:

于是就改用了conventional-changelog-cli

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

通过以上命令你就会发现在项目中多了个CHANGELOG.md文件,表示生成 Change log成功了。

参考链接:

Commit message 和 Change log 编写指南
Git Commit Message Conventions
Angular的 Commit Message Guidelines
Angular的commit message
Git 写出好的 commit message

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 212,294评论 6 493
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 90,493评论 3 385
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 157,790评论 0 348
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 56,595评论 1 284
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 65,718评论 6 386
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,906评论 1 290
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 39,053评论 3 410
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,797评论 0 268
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,250评论 1 303
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,570评论 2 327
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,711评论 1 341
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,388评论 4 332
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 40,018评论 3 316
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,796评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,023评论 1 266
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 46,461评论 2 360
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 43,595评论 2 350

推荐阅读更多精彩内容