zoukankan      html  css  js  c++  java

  • Git Commit Message规范

     1、Commit Message的好处

    规范化后的commit message主要好处有以下几点：

    • 让维护者知道变化的性质和原因
    • 方便过滤快速查找信息
    • 自动化生成格式化的Change Log

    2、Commit Message格式

    Angular规范是目前应用最为广泛的写法，包括三个部分：Header，Body 和 Footer，和约定式提交类似，格式如下：

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

    其中，header 是必需的，body 和 footer 可以省略。不管哪个部分，任一行都不得超过72个字符（或100个字符）。

    2.1 Header

     Header部分只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。

    type

    commit类型，只能是下面其中一个：

    • build: 构造工具的或者外部依赖的改动，如 gulp, broccoli, npm
    • ci: 与CI（持续集成服务）配置文件和脚本有关的改动，如 Travis, Circle, BrowserStack, SauceLabs
    • docs: 只改动了文档相关的内容
    • feat: 增加新功能
    • fix: 修复bug
    • perf: 提高性能的改动
    • refactor: 代码重构，没有加新功能或者修复bug
    • style:不影响代码含义的改动，例如去掉空格、改变缩进、增删分号
    • test: 增加或修正测试
    • chore: 不修改src或者test的其余修改，例如构建过程或辅助工具的变动

    以上几种类型，推荐使用feat和fix，两者分别和语义化版本中的minor和patch相对应，且一定会出现在Change Log中。

    scope

    用于描述改动的范围，格式可以是项目名/模块名，如：angular/common。如果一次commit修改多个模块，建议拆分成多次commit，以便更好追踪和维护。

    subject

    subject是commit的简短描述，其要求：

    • 以动词开头，使用祈使语句和现在时态，比如change，而不是changed或changes
    • 第一个字母小写
    • 结尾不加句号（.）

    2.2 Body

    Body为详细描述，可以写成多行。对于小的修改不作要求，但是重大需求、更新等必须添加body来作说明。

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

    2.3 Footer

    Footer包含两种情况：不兼容变动和关闭Issue。

    破坏性变更

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

    BREAKING CHANGE: environment variables now take precedence over config files.

    涉及破坏性变更和语义化版本中的major相对应，如果存在则必须指明该项，如：版本升级、接口参数减少、接口删除、迁移等。

    关闭Issue

    如果当前commit针对某个issue，那么可以在 Footer 部分关闭这个 issue 。如：

    Closes #111
re #222
fix #333
    fix #444,#555

    2.4 Revert

    Revert是一种特殊情况，如果当前commit用于撤销以前的commit，则必须以 revert:  开头，后面跟着被撤销commit的Header。Body部分的格式是固定的，必须写成 This reverts commit <hash>. ，其中的hash是被撤销 commit 的 SHA 标识符，如：

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

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

    2.5 一个commit例子

    build(pom): 升级springboot版本到XXX

为了支持XXX特性，需要升级springboot版本到XXX

BREAKING CHANGE: 随着springboot版本更新到XXX，项目中使用的XXX方法不再被支持

Closes #323

    下图是angular项目github上的提交记录：

    3、Conventional-Changelog

    conventional-changelog是一款可以根据项目的commit 和 metadata信息自动生成 changelogs 和 release notes的系列工具，并且在辅助 standard-version 工具的情况下，可以自动帮你完成生成version、打tag, 生成CHANGELOG等系列过程。

     支持的插件有：grunt、gulp、atom、vscode，其生态主要模块如下：

    这里主要介绍commitizen、commitlint、conventional-changelog-cli 和standard-version 等4个工具。

    3.1 commitizen提交

    commitizen是一个撰写合格commit message的工具，用于代替git commit 指令。

    commitizen安装

    # 全局安装
    npm install -g commitizen
# 本地安装
npm install --save-dev commitizen

    安装适配器（Adapter)

    commitizen支持不同适配器的扩展，从而去满足不同的构建需求。cz-conventional-changelog适配器提供conventional-changelog标准（约定式提交标准），更多查看。

    ###全局安装###
npm install -g commitizen cz-conventional-changelog
# 全局模式需要配置文件指定adapter
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc  

###本地安装###
npm install cz-conventional-changelog --save-dev
# 或者使用 commitizen 工具
commitizen init cz-conventional-changelog --save-dev --save-exact

     安装并添加完后，使用 git cz 命令替换 git commit 提交记录，如下图所示：

     3.2 commitlint验证

    安装commitlint

    # Install commitlint cli and conventional config
npm install --save-dev @commitlint/{config-conventional,cli}
# For Windows:
npm install --save-dev @commitlint/config-conventional @commitlint/cli

# Configure commitlint to use conventional config
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

    安装husky

    #npm
npm install husky --save-dev
#yarn
yarn add -D husky

    添加如下代码到package.json文件中

    {
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

    安装完成后，输入测试命令，如下图所示：

     3.3 conventional-changelog-cli生成

     conventional-changelog-cli 默认推荐的 commit 标准是来自angular项目,除了angular标准以外，目前集成了包括 atom, codemirror, ember, eslint, express, jquery 等项目的标准。

    安装

    npm install -g conventional-changelog-cli

    使用

    conventional-changelog -p angular -i CHANGELOG.md -s

    上面命令会在CHANGELOG.md头部加上自上次tag版本的之后的变更（Feature、Fix、Breaking Changes等）。如果要生成所有发布的Change Log，则运行命令如下：

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

    参数说明：-p用来指定使用的commit message标准；-i表示从哪里读取changelog；-s表示读写changelog为同一文件；-r表示生成 changelog所需要使用的release版本数量，默认为1，全部则是0。

    为了方便使用，可以将其写入package.json的scripts字段，如下所示：

    {
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
  }
}

    以后使用时，直接运行命令 npm run changelog 即可。

    自定义参数

    生成的 changlog 中有些常用内容可以通过自定义参数来根据需求更改，例如版本号、commit 地址等。changelog 中生成的版本号即是从 package.json 中获取 version 字段来的。commit 连接的仓库地址我们需要修改 package.json 中的repository地址，changelog 中 issuse 默认的连接地址也是根据 repository 来生成的。如果你使用了第三方的协作系统（例如 bitbucket）， 那么你可以使用这个标准conventional-changelog-angular-bitbucket。如果使用 redmine 来管理 isssue，那么在生成 changelog 后可以使用命令 bash ./script/changeissueurl.sh CHANGELOG.md 处理文本中的原有地址，脚本文件如下：

    #!/bin/bash
sed -i 's|https://github.com/aaron-shu/gitStudy/issues/|https://redmine.example.com/|g' $1

    conventional-changelog 更多的选项配置可以看这里。

    3.4 standard-version生成

    standard-version是一款遵循语义化版本（ semver）和 commit message 标准规范 的版本和 changlog 自动化工具。通常情况线下，我们会在 master 分支进行如下的版本发布操作：

    1. git pull origin master
    2. 根据 pacakage.json 中的 version 更新版本号，更新 changelog
    3. git add -A, 然后 git commit
    4. git tag 打版本操作
    5. push 版本 tag 和 master 分支到仓库

    其中2，3，4是 standard-version 工具会自动完成的工作，配合本地的 shell 脚本，则可以自动完成一系列版本发布的工作。

    安装&使用

    # 全局
npm install -g standard-version
# 本地
npm install --save-dev standard-version

# 使用
    # Help standard-version --help
standard-version

    执行 standard-version 命令，我们会在控制台看到整个执行流程的 log 信息。默认情况下，工具会自动根据主版本（major）、次版本（ minor）和修订版（patch） 规则生成版本号，比如package.json中的version为1.0.0，那么执行后则是：1.0.1。

    几个常用参数

    • --release-as, -r 指定版本号
    • --prerelease, -p 预发版本命名
    • --tag-prefix, -t 版本 tag 前缀
    # 如果当前是1.0.1，则输出版本1.1.0
standard-version -r minor
# 指定输出版本2.0.0
standard-version -r 2.0.0
# 指定输出版本2.0.0-test
standard-version -r 2.0.0-test

# 如果当前是2.0.0-alpha.0，则输出版本2.0.0-alpha.1
standard-version --prerelease alpha

# 如果当前是2.0.0，则输出stable-2.0.1
standard-version --tag-prefix "stable-"

     3.5 npm集成

    将命令集成到 npm package.json的 scripts 中, 并配合 shell 脚本使用，如下：

    "scripts": {
    "release": "bash ./scripts/release.sh",
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md && npm run changeissueurl",
    "changeissueurl": "bash ./scripts/changeissueurl.sh CHANGELOG.md"
  }
    // 配置好后使用 npm run 执行发布
    npm run release

    添加 release.sh 脚本：

    #!/bin/bash

# Release branch
master="master"
prefix="stable-"

git pull origin $master
echo "Current pull origin $master."

# Auto generate version number and tag
standard-version --tag-prefix $prefix

git push --follow-tags origin $master

echo "Git push origin $master"
echo "Release finished."

    上面的脚本只是做了简单的分支 pull，执行 standard-version 和最后的版本 push 工作，如果要做一些定制化的执行参数，则需要做定制修改了。

    4、一些插件

    IDEA：Git Commit Template（提交模板）

    VSCode：git-commit-plugin（提交模板，不同的提交类型前会添加图标）、changelog-generator（change log生成）
  • 相关阅读:
    Android 查看通讯录Contacts是否发生变化
    卓尼斯ZT-180评測
    C++中的单例模式
    Android 动画之ScaleAnimation应用具体解释
    java的静态代理
    词性标注
    ubuntu 11.04安装笔记
    机房收费系统学生下机结账小结
    MyBatis入门学习（一）
    ！！！！OpenWrt系列教程汇总
  • 原文地址：https://www.cnblogs.com/aaron-shu/p/14018687.html
Copyright © 2011-2022 走看看