Standardize GIT code submission information and automate version management

May 31, 2021 Article blog

1. preface

2. Why should you standardize the submission of information?

3. What specification to use

preface

git As an essential tool for developers, code submission is also a very frequent daily operation, and if you or your team do not currently have a specification or constraint on submitting information, then it is necessary to look at the content of this article.

Why should you standardize the submission of information?

It is certainly necessary to standardize the submission of information in the first place, and a brief summary of the following benefits:

Let the maintenance or use personnel of the project know what changes have been submitted
Clear history, maybe one day you need to find it yourself
Specification commit records can be used to automatically generate modification logs (CHANGELOG. MD)
Trigger the build and deployment process based on the type of commit

What specification to use

Conventional Commits the most widely used submission information specification to date, is inspired by the AngularJS specification, and here is the structure of the specification information:

[optional scope]: 
//空一行
[optional body]
//空一行
[optional footer(s)]

Specification description

type category submitted by type must be one of the following types

feat：增加一个新功能
fix：修复bug
docs：只修改了文档
style：做了不影响代码含义的修改，空格、格式化、缺少分号等等
refactor：代码重构，既不是修复bug，也不是新功能的修改
perf：改进性能的代码
test：增加测试或更新已有的测试
chore：构建或辅助工具或依赖库的更新

scope optional, representing the scope, functionality, and modules of impact

subject required, simple description, no more than 50 words

body optional to fill in a more detailed description

footer optional, used to fill in the associated issus or BREAK CHANGE

BREAKING CHANGE

Must be capitalized to indicate that a destructive API change has been introduced, usually a large version of the change, BREAKING CHANGE: A description must then be provided, followed by a commit example that contains the destructive change

feat: allow provided config object to extend other configs


BREAKING CHANGE: `extends` key in config file is now used for extending other config files

For more detailed instructions, see the convention submission specification

How to constrain the specification

How to ensure that each commit is compliant, the best way is through tools to generate and verify, commitizen is a nodejs command line tool, through interactive means, to generate specification-compliant git commit, the interface is as follows:

Standardize GIT code submission information and automate version management1

Start the installation:

# 全局安装
npm install -g commitizen 
# 或者本地安装
$ npm install --save-dev commitizen
# 安装适配器
npm install cz-conventional-changelog

packages.json specifies which specification to use in the configuration file

...
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }

Once installed, you can use git cz of git commit and then enter step by step based on the prompts

Format check commitlint

Perhaps you don't want to build through an interactive interface every time, or you want to use git commit -m 'message' so to ensure that the information is correct, you can combine husky to format the submitted information

Installation dependency

npm install --save-dev @commitlint/{config-conventional,cli}
# 安装husky
npm install --save-dev husky

Add commitlint.config.js file to the project

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
``` 
`package.json`配置
#git提交验证
“husky”: {
“hooks”: {
“commit-msg”: “commitlint -E HUSKY_GIT_PARAMS”
}
},

OK to this point is completed, and finally give you the project README. MD plus a commitizen-friendly logo

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg) _blank](http://commitizen.github.io/cz-cli/)


## 自动版本管理和生成CHANGELOG


规范化的提交信息除了能很好描述项目的修改，还有一个很好的作用就是能根据提交记录来生成CHANGELOG.MD和自动生成版本号等功能。




### standard-version


一个用于生成`CHANGELOG.md`和进行`SemVer(语义化版本号)`发版的命令行工具


主要功能：
* 自动修改最新版本号，可以是`package.json`或者自定义一个文件
* 读取最新版本号，创建一个最新的`git tag`
* 根据提交信息，生成`CHANGELOG.md`
* 创建一个新提交包括 `CHANGELOG.md`和`package.json`




### 语义化版本控制(SemVer)


先简单了解下什么是语义化的版本控制，其是由`GitHub`发起的一份用于规范版本号递增的规则，
##### 版本格式
主版本号.次版本号.修订号，版本号递增规则如下：


* 主版本号(major)：当你做了不兼容的 API 修改，
* 次版本号(minor)：当你做了向下兼容的功能性新增，可以理解为Feature版本，
* 修订号(patch)：当你做了向下兼容的问题修正，可以理解为Bug fix版本。


先行版本号可以加到“主版本号.次版本号.修订号”的后面，作为延伸。


##### 先行版本
当即将发布大版本改动前，但是又不能保证这个版本的功能 100% 正常，这个时候可以发布先行版本：


* alpha: 内部版本
* beta: 公测版本
* rc: 候选版本(Release candiate)


比如：1.0.0-alpha.0,1.0.0-alpha.1,1.0.0-rc.0,1.0.0-rc.1等。


 `standard-version` 会根据提交的信息类型来自动更改对应的版本号,如下:
* feat: 次版本(minor)+1
* fix: 修订号(patch) +1
* BREAK CHANGE: 主板号(marjor) +1


> `standard-verstion` 生成的`CHANGELOG`只会包含`feat`,`fix`,`BREACK-CHANGE`类型的提交记录




#### 使用
``` bash
npm i --save-dev standard-version

Add npm script

{
 scripts:{
   "release": "standard-version",
   "release:alpha": "standard-version --prerelease alpha",
   "release:rc": "standard-version --prerelease rc"
  }
}

execute:

# npm run script
npm run release
# or global bin
standard-version

Or you want to specify a release number:

#指定类型 patch/minor/marjor
npm run release -- --release-as patch
#指定版本号
npm run release -- -- release-as 1.1.0

life cycle

prerelease Before all scripts are executed
prebump / postbump : Before and after modifying the version number
prechangelog / postchangelog After generating changelog and generating changelog
pretag / postag Build tag tags and after

standard-version itself is local and does not operate without push and after we generate the tag at the last step, we can perform the push operation and add it to paceage.json

"standard-version": {
    "scripts": {
      "posttag": "git push --follow-tags origin master && npm publish"
    }
  }

There are many more configuration features to check the official documentation for yourself

Other similar tools

In addition to standard-version there are other similar tools that you can learn about

Modify Git Commit

In order to make CHANGELOG.MD provides a more intuitive view of each version of the modification, and we try to make sure that each commit makes sense, but in practice, some incorrect commit messages are inevitably submitted, and here are a few git commands to modify commit

1 Modify the last commit

git commit --amend

The command creates a commit and overrides the last commit, which is ideal if it is incorrectly written or not satisfied with the last commit.

2 Merge multiple commits

git reset --soft [commitID]

If you want to combine the last few commits, you'll need to use the command above to specify the ccommitId to undo, which preserves the current changes and undoes all commit records after the specified commit, and if you don't specify the ID, you can use HEAD {num} select the most recent {num}

git reset --soft HEAD~2 #合并最近两条提交
git commit -m 'feat: add new feat'

The difference with the --soft parameter is that adding changes to the staging area is equivalent to executing git add .

git rebase -i

git rebase will be even more powerful if I want to modify the last 3 commit records to execute

git rebase -i  HEAD~3

The following editor interface (vim editor) appears:

Standardize GIT code submission information and automate version management3

Shown above is my last 3 submissions, here is the command description, modified by changing the pick before commit information to the command you need, and then exiting :wq save

Here are common command instructions:

p,pick = 使用提交
r,reword = 使用提交，但修改提交说明
e,edit = 使用提交，退出后使用git commit --amend 修改
s,squash = 使用提交，合并前一个提交
f,fixup = 和squash相同，但丢弃提交说明日志
d,drop = 删除提交，丢弃提交记录

At last

The text focuses on how to standardize git commit and automatic semantic version management, and how to modify git commit to follow a specification that doesn't actually add much more work than filling out information at will, but relying on specifications can do more to improve efficiency.