git提交规范

一、规范的好处

当我们提交代码的时候,需要编写提交信息(commit message)。而提交信息的主要用途是:告诉这个项目的人,这次代码提交里做了些什么。所以每次的提交信息大家应该按照某种规范进行提交,最好是能有规范和工具的约束。

  • 易于阅读,在最短时间清楚每次提交的意义

    良好的Git提交日志非常重要,最明显的一点是,它让整个Git提交历史的阅读变得非常轻松。大多数情况下,看提交历史的人跟提交代码的人都不是同一个人,当别人阅读你的提交历史时,他很可能是不知道具体代码细节的,你如何在最短的时间内让他一眼知道每次提交的意义

    • 每次提交影响的具体范围?
    • 这个bug在哪次提交中被修复了?
    • 这个新功能是在哪次提交中增加的?
    • 修改是否向下兼容?
    • 是否回滚了代码?
    • 是否只是修改了文档、调整了代码格式?
    • 是否修改了测试、是否进行了重构?
    • 是否对代码进行了性能优化?
  • 提供更多的历史信息,方便快速浏览。

    git log <branch/tag> HEAD --pretty=format:%s
    

  • 便于快速查找信息

    可以过滤筛选某些commit

    git log <branch/tag> HEAD --grep feature
    
  • 生成CHANGELOG

    规范的Git提交历史,还可以直接生成项目发版的CHANGELOG

二、开源社区的Angular提交规范

与我们日常工作稍有不同的是:工作中的 Release 计划一般都是事先安排好的,不需要一些 CHANGELOG 什么的。而开源应用、开源库需要有对应的 CHANELOG,则添加了什么功能、修改了什么等等。毕竟有很多东西是由社区来维护的。目前,社区有多种 Commit message 的写法规范。Angular 规范是目前使用最广的写法,比较合理和系统化,并且有配套的工具。

1. Angular规范的格式:

每个提交消息都由一个标题、一个正文和一个页脚组成。而标题又具有特殊格式,包括修改类型、影响范围和内容主题

<type修改类型>(<scope影响范围>): <subject标题或描述>
<--空行-->
[body正文]
<--空行-->
[footer注脚]
=============中文版==================
注意:
  <>中为必填项
  []中为可选项
  提交消息的任何一行都不能超过100个字符(为了让消息在GitHub以及各种Git工具中都更容易阅读)

type: 修改类型

每个类型值都表示了不同的含义,类型值必须是以下的其中一个:

  • 主要type
    • feat:提交了新功能
    • fix:修复了bug
  • 次要type
    • docs:只改动了文档相关的内容
    • style:调整代码格式,未修改代码逻辑(比如修改空格、格式化、缺少分号等)
    • refactor:代码重构,既没修复bug也没有添加新功能
    • build:构造工具或者外部依赖的改动,例如webpack,npm,pom
  • 特殊type
    • perf:性能优化,提高性能的代码更改
    • test:添加或修改代码测试
    • ci:与CI(持续集成服务)有关的改动
    • chore:对构建流程或辅助工具和依赖库(如文档生成等)的更改

当一次改动包括主要type与次要type时,统一采用主要type。

scope: 影响范围

  • scope也为必填项,用于描述改动的范围,格式为项目名/模块名,例如:node-pc/common rrd-h5/activity,而we-sdk不需指定模块名。如果一次commit修改多个模块,建议拆分成多次commit,以便更好追踪和维护。

  • 当修改影响多个范围时,也可以使用“*”。

  • 它可以是你提交代码实际影响到的任何内容。例如$location、$browser、$compile、$rootScope、ngHref、ngClick、ngView等,唯一需要注意的是它必须足够简短。

subject: 标题

标题是对变更的简明描述:

  • 使用祈使句,现在时态:是“change”不是“changed”也不是“changes”
  • 不要大写首字母
  • 结尾不要使用句号

body: 正文

正文是对标题的补充,但它不是必须的。和标题一样,它也要求使用祈使句且现在时态,正文应该包含更详细的信息,如代码修改的动机,与修改前的代码对比等。

当有以下两种情况需要写footer注脚:

  • 不兼容的改变

    如果当前代码有重大更改,应该以BREAKING CHANGE这个词开头,带一个空格或者两个换行符,然后是对变动的描述,变动理由以及如何迁移。

  • 关闭issue

    如果当前commit针对某个issue,可以以Closes为开头。

任何Breaking Changes(破坏性变更,不向下兼容)都应该在页脚中进行说明,它经常也用来引用本次提交解决的GitHub Issue

Breaking Changes应该以“BREAKING CHANGE:”开头,然后紧跟一个空格或两个换行符,其他要求与前面一致。

Revert

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

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

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

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

如果当前 commit 与被撤销的 commit,在同一个发布(release)里面,那么它们都不会出现在 Change log 里面。如果两者在不同的发布,那么当前 commit,会出现在 Change log 的Reverts小标题下面。

2、提交规范的辅助工具

IDEA插件Git Commit Template

commitizen: 辅助撰写格式化的commit message

  1. 安装、配置
npm install -g commitizen
  1. commitizen工具是基于Node.js的,而非前端项目工程目录下是没有package.json文件,所以会报错:
npm WARN saveError ENOENT: no such file or directory, open './package.json'
npm WARN enoent ENOENT: no such file or directory, open './package.json'

对于此种错误,创建一个空的package.json文件,然后进入到项目目录,执行

npm init --yes
  1. 在项目目录里,使其支持 Angular 的 Commit message 格式。
commitizen init cz-conventional-changelog --save --save-exact
  1. 以后,凡是用到git commit命令,一律改为使用git cz。这时,就会出现选项,用来生成符合格式的 Commit message。

conventional-changelog: 生成CHANGELOG

如果你的所有 Commit 都符合 Angular 格式,那么发布新版本时, Change log 就可以用脚本自动生成,生成的文档包括以下三个部分。

  • New features
  • Bug fixes
  • Breaking changes

安装配置

npm install -g conventional-changelog

# 生成CHANGELOG
conventional-changelog -p angular -i CHANGELOG.md -w
    # 命令不会覆盖以前的 Change log,只会在CHANGELOG.md的头部加上自从上次发布以来的变动

# 生成所有发布的 Change log
conventional-changelog -p angular -i CHANGELOG.md -w -r 0

三、基于Jira的提交规范

Copyright Curiouser all right reserved,powered by Gitbook该文件最后修改时间: 2020-06-16 21:35:29

results matching ""

    No results matching ""