git工程化自动生成changeLog 发布版本

客官°小女子只卖身不卖艺 2023-02-19 15:25 14阅读 0赞

# git log 生成 changeLog #

在进行git仓库的自动化管理时，发布前往往需要CI服务器自动生成 `CHANGELOG.MD` ，本文介绍如何自动changeLog.md自动生成的思路。

### 文章目录 ###

*  git log 生成 changeLog
 *   *  生成流程
     *  关键问题
     *   *  使用 Git 自带的提交模板 Commit Template 来解决
         *   *  一、在工程的根目录下建立模板文件
             *  二、设置模板
             *  三、提交代码
         *  以工具的方式解决
     *  其他
     *   *  git commit 格式基本规约：50/72格式化
         *  git commit 风格
         *   *  模板：
             *  详细说明：

## 生成流程 ##

*  多次 commit -m “xxx”
 *  使用命令 `git log > log` 生成提交记录 log 文件
 *  处理 log 文件提取关心的信息, 然后转成 `CHANGELOG.MD` 文件.
    
     *  思路：（log文件中包含了所有的commit信息, 包括id, author, date以及comment等）
     *  前提：需要规范团队 git commit 的格式，才能保证自动生成

> 为什么基于commit的, 不是基于merge？  
> 因为merge信息的获取需要使用gitlab提供的API, 不如获取commit来的方便（'git log > log’一条命令即可）。大多数的开源仓库的changelog也是基于commit

## 关键问题 ##

*  如何规范团队 git commit 的格式？

这个问题并不是难题，关键是如何让团队成员容易掌握提交格式（简单通用），又方便程序处理（格式规范），我们可以联想到使用提交模板来解决。

*  可以对 git 客户端进行增强（如 [IDEA 的插件][IDEA]）
    
     *  但如果某些成员不用 IDEA ，那就不能轻松的记住提交格式
 *   *

### 使用 Git 自带的提交模板 Commit Template 来解决 ###

在命令行里 `git commit` 时，自动使用设置的编辑器打开设置的模板。开发者只需在预设模板的基础上添加或修改相应内容即可。（个人项目通常选择这种方式，简单）

#### 一、在工程的根目录下建立模板文件 ####

新建 `gitcommit_template` 文件，将希望的模板填充进去：

*  例1：

[部门][项目]:
    问题原因:
    解决方法:
    变更类别:
    适用机型:
    验证建议:
    关联变更项：
    任务 Id:

*  例2：

# 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
    
    # Commitizen

#### 二、设置模板 ####

有以下几种设置方式

*  设置当前分支的提交模板  
    git config commit.template \[模板文件名\]  
    如：`git config commit.template gitcommit_template`
 *  设置全局的提交模板  
    git config --global commit.template \[模板文件名\]  
    如：`git config --global commit.template gitcommit_template`
 *  设置文本编辑器  
    git config -global core.editor \[编辑器名称\]  
    如:`git config -global core.editor vim`

#### 三、提交代码 ####

在命令行里 `git commit` 时，自动使用设置的编辑器打开设置的模板。在预设模板的基础上添加或修改相应内容即可。

然后`git push`提交到远程分支。

### 以工具的方式解决 ###

模板的方式是git原生支持的，模板也可以自定义，定制性强，但与工具相比还不够方便，下面介绍几种这方面的工具。

*  conventional-changelog
 *  commitizen
 *  conventional-changelog-cli
 *  standard-version

--------------------

## 其他 ##

### git commit 格式基本规约：50/72格式化 ###

*  第一行不超过50个字符
 *  然后是空白行
 *  其余文字应以72个字符换行

原因：

*  一些工具将第一行作为主题行，将第二段作为正文(类似于电子邮件)。若工具流行，那么该格式将流行。
 *  `git log`不处理换行，因此如果行太长则很难阅读。
 *  `git format-patch --stdout` 可以将提交转换为电子邮件。

### git commit 风格 ###

不同的人，有不同的表达风格，还有很多风骚的格式，如用 emoji 的, 用唐诗的, 用随机生成的. 风格没有对错, 只要能够体现出 commit 所做的修改即可。但规范 git commit 的风格有利于仓库的维护和新加入团队成员的快速上手。

目前比较建议的是，使用终端工具  
`commitizen/cz-cli` \+ `commitizen/cz-conventional-changelog` \+ `conventional-changelog/standard-version` 一步解决提交信息和版本发布。

如果希望强制执行，可以在持续集成里面加入 `marionebl/commitlint` 检查 commit 信息是否符合规范。

目前规范使用较多的是 Angular 团队的规范, 继而衍生了 Conventional Commits specification. 很多工具也是基于此规范, 它的 message 格式分为三行，这三行的详细介绍如下

标题: 【必填】  简单描述修改类型和内容
    正文内容: 对本次提交的详细介绍，如为什么修改，怎么修改的,，开发思路是什么等等
    页脚注释: 放 Breaking Changes 或 Closed Issues

#### 模板： ####

> 其中 `<>` 尖括号中的为具体内容，`<BLANK LINE>`为空行。

#### 详细说明： ####

*  `type`: 修改类型
    
     *  `feat`: 新特性
     *  `fix`: 修改问题
     *  `refactor`: 代码重构
     *  `docs`: 文档修改
     *  `style`: 代码格式修改， 注意不是 css 修改
     *  `test`: 测试用例修改
     *  `chore`: 其他修改， 比如构建流程， 依赖管理。
     *  `revert`: 用于撤销以前的 commit 详见后面特殊情况注释。
 *  `scope`: 影响的范围， 一般为自己代码的模块名。
 *  `subject`: 概述。建议符合 50/72 格式。
 *  `body`: 具体修改内容， 可以分为多行。建议符合 50/72 格式。
 *  `footer`: 一些备注， 通常是 BREAKING CHANGE 或修复的 bug 的链接。

> 特殊情况【回滚，Revert】：如果当前 commit 用于撤销以前的 commit，  
> 必须以revert:开头，后面跟着被撤销 Commit 的 Header。  
> Body部分的格式是固定的，必须写成 `This reverts commit <hash>.`，其中的hash是被撤销 commit 的 SHA 标识符。  
> 如果当前 commit 与被撤销的 commit，在同一个发布（release）里面，那么它们都不会出现在 Change log 里面。  
> 如果两者在不同的发布，那么当前 commit，会出现在 Change log 的Reverts小标题下面。

--------------------

参考：  
[工具参考][Link 1]  
[50/70格式][50_70]  
[提交风格][Link 2]

[IDEA]: https://plugins.jetbrains.com/plugin/9861-git-commit-template
[Link 1]: http://imziv.com/blog/article/read.htm?id=91
[50_70]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[Link 2]: https://www.sohu.com/a/225520315_500651