规范git commit提交记录和版本发布记录

在开发过程中我们一般都会用到git管理代码，在git commit提交代码时我们一般对git commit message随便写点简单的描述，可是随着项目参与人数的增多，发现提交的commit记录越来越杂乱，不便查阅，在网上找了下解决方案，总结一下方便在公司项目中运用。

commit message 格式

目前大家比较认可的是Angular团队的提交规范，很多工具也是基于此规范开发的。该提交规范格式如下:

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

每一个commit message由header（必填）、body（选填）和footer（选填）组成，header部分包括三个字段：type（必填）、scope（选填）和 subject（必填）。为了方便浏览，每一行的commit message不应超过100个字符。

type

type 用于说明提交的commit的类别，有一下几种类型：

feat：添加新功能（feature）
fix：改bug
docs：修改文档（documentation）
style：只改样式（不影响代码运行的变动）
refactor：重构（即不是新增功能，也不是改bug的代码变动）
perf : 代码优化（提升代码性能）
test：增加测试
chore：构建过程或辅助工具的变动

scope

本次改动影响的范围

subject

对本次改动的简单描述

body

commit 具体修改内容的详细描述, 可以分为多行

footer

一些备注, 通常是 BREAKING CHANGE 或修复的 bug 的链接.

如何规范提交记录

上面介绍的是通用的git commit message规范，可是在git commit的时候如何用这写规范来写呢？

如果是个人项目我们可以为 git 设置 commit template, 每次 git commit 的时候在 vim 中自动带上模板信息, 自己只要按照模板信息填写就行

修改~/.gitconfig(.git/config文件), 添加:

[commit]
    template = .git_template

新建.git_template 内容可如下：

# head: <type>(<scope>): <subject>
# - type: feat, fix, docs, style, refactor, test, chore
# - scope: can be empty (eg. if the change is a global or difficult to assign to a single component)
# - subject: start with verb (such as 'change'), 50-character line
#
# body: 72-character wrapped. This should answer:
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# footer:
# - Include a link to the ticket, if any.
# - BREAKING CHANGE
#

这样在项目中执行git commit时vim编辑会带上这些信息

如果我们的项目是多人参与的项目，这样就不合适了。这里我们推荐使用cz-customizable工具生成和约束commit message

cz-customizable有两种使用方式，这里我们采用官方推荐的第二种方式

安装cz-customizable

npm install  cz-customizable --save-dev

修改package.json文件，在scripts中加入commit命令

"scripts" : {
  ...
  "commit": "./node_modules/cz-customizable/standalone.js"
}

新建.cz-config.js文件

module.exports = {
types: [
    { value: 'feat', name: 'feat: A new feature' },
    { value: 'fix', name: 'fix: A bug fix' },
    { value: 'docs', name: 'docs: Documentation only changes' },
    {
        value: 'style',
        name: 'style: Changes that do not affect the meaning of the code\n (white-space, formatting, missing semi-colons, etc)',
    },
    {
        value: 'refactor',
        name: 'refactor: A code change that neither fixes a bug nor adds a feature',
    },
    {
        value: 'perf',
        name: 'perf: A code change that improves performance',
    },
    { value: 'test', name: 'test: Adding missing tests' },
    {
        value: 'chore',
        name:'chore: Changes to the build process or auxiliary tools\n and libraries such as documentation generation',
    }
],
scopes: [{ name: ''common }, { name: 'route' }, { name: 'components' }],
allowTicketNumber: false,
isTicketNumberRequired: false,
ticketNumberPrefix: 'TICKET-',
ticketNumberRegExp: '\\d{1,5}',
// it needs to match the value for field type. Eg.: 'fix'
/*
scopeOverrides: {
fix: [
{name: 'merge'},
{name: 'style'},
{name: 'e2eTest'},
{name: 'unitTest'}
]
},
*/
// override the messages, defaults are as follows
messages: {
    type: "Select the type of change that you're committing:",
    scope: '\nDenote the SCOPE of this change (optional):',
    // used if allowCustomScopes is true
    customScope: 'Denote the SCOPE of this change:',
    subject: 'Write a SHORT, IMPERATIVE tense description of the change:\n',
    body: 'Provide a LONGER description of the change (optional). Use "|" to break new line:\n',
    breaking: 'List any BREAKING CHANGES (optional):\n',
    footer: 'List any ISSUES CLOSED by this change (optional). E.g.: #31, #34:\n',
    confirmCommit: 'Are you sure you want to proceed with the commit above?',
},
allowCustomScopes: true,
allowBreakingChanges: ['feat', 'fix'],
// skip any questions you want
skipQuestions: ['body','breaking','footer'],
// limit subject length
subjectLimit: 100,
// breaklineChar: '|', // It is supported for fields body and footer.
// footerPrefix : 'ISSUES CLOSED:'
// askForBreakingChangeFirst : true, // default is false
};

该文件的配置信息可参考options

至此我们在提交代码时不在使用git commit命令，而是使用npm run commit这样就可以按照规范输出commit message。

校验commit message

上面的配置中我们并没有对commit message进行校验，也就是说如果项目中有成员继续使用git commit -m "message"提交仍是可以的，如果想增加commit message校验可以使用validate-commit-msg工具

安装相关依赖包

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

在package.json文件中增加以下配置

"husky": {
    "hooks": {
        "commit-msg": "validate-commit-msg"
    }
}

这样我们团队中如果有成员使用git commit -m 'message'提交时，会提交不通过的提示

$ git commit -m 'aaa'
husky > commit-msg (node v8.11.3)
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" !
aaa
husky > commit-msg hook failed (add --no-verify to bypass)

至此用cz-customizable规范git commit提交记录配置完成

记录版本发布

在之前的前端开发脚手架项目改动时，我们总是手动编写README文件，将做出的哪些改变一一列出来方便团队成员浏览知晓，后来在网上查阅参考别的项目得知我们可以通过

standard-version工具自动生成CHANGLOG文件记录版本变动

安装

npm install  standard-version --save-dev

修改package.json文件，在scripts中加入release命令

"scripts": {
    ...
    "release": "standard-version"
},

执行npm run release即可生成CHANGELOG文件，该文件中包含Features和Bug Fixes的提交记录

standard-version命令参数介绍

  --release-as, -r     Specify the release type manually (like npm version <major|minor|patch|1.1.0>) [字符串]
  // major: 1.0.0 -> 2.0.0, minor: 1.0.0 -> 1.1.0, patch : 1.0.0 -> 1.0.1
  --prerelease, -p     make a pre-release with optional option value to specify a tag id [字符串]
  --infile, -i         Read the CHANGELOG from this file                 [默认值: "CHANGELOG.md"]
  --message, -m        Commit message, replaces %s with new version [字符串] [默认值: "chore(release): %s"]
  --first-release, -f  Is this the first release?                          [布尔] [默认值: false]
  --sign, -s           Should the git commit and tag be signed?            [布尔] [默认值: false]
  --no-verify, -n      Bypass pre-commit or commit-msg git hooks during the commit phase [布尔] [默认值: false]
  --commit-all, -a     Commit all staged changes, not just files affected by standard-version [布尔] [默认值: false]
  --silent             Don't print logs and errors                         [布尔] [默认值: false]
  --tag-prefix, -t     Set a custom prefix for the git tag to be created   [字符串] [默认值: "v"]
  --scripts            Provide scripts to execute for lifecycle events (prebump, precommit, [默认值: {}]
  --skip               Map of steps in the release process that should be skipped    [默认值: {}]
  --dry-run            See the commands that running standard-version would run [布尔] [默认值: false]

// 第一次发布版本

npm run release -f

// 指定发布版本等级

npm run release -r minor

注意

使用standard-version生成CHANGELOG之前需要有完整的package.json文件，特别是有

"repository": {
    "type": "git",
    "url": "***"
}

否则生成的compare链接不完整，小编就犯过这个错

参考文章