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

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 ,那就不能轻松的记住提交格式

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

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

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

新建 gitcommit_template 文件,将希望的模板填充进去:

  • 例1:
[部门][项目]:
问题原因:
解决方法:
变更类别:
适用机型:
验证建议:
关联变更项:
任务 Id:
  • 例2:
# head: (): 
# - 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

模板:

(): 



其中 <> 尖括号中的为具体内容,为空行。

详细说明:

  • 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是被撤销 commit 的 SHA 标识符。
如果当前 commit 与被撤销的 commit,在同一个发布(release)里面,那么它们都不会出现在 Change log 里面。
如果两者在不同的发布,那么当前 commit,会出现在 Change log 的Reverts小标题下面。


参考:
工具参考
50/70格式
提交风格

你可能感兴趣的:(git)