如何为你的项目生成 CHANGELOG，以提高项目的可维护性？
大家好，我是孔令飞，字节跳动云原生开发专家、云原生实战营 知识星球星主。欢迎关注我的公众号【令飞编程】，Go、云原生干货不错过。
在 Go 项目开发中， 为了提高项目的可维护性、可阅读性，很多优秀的项目都会在项目根目录下放上一个名为 CHANGELOG.md 的文件或者 CHANGELOG 目录。你可以通过这些文件清晰的知道项目发布了哪些版本，每个版本又有哪些变更。在感受到 CHANGELOG 文件提供便捷版本概览功能的同时，你是否好奇这些 CHANGELOG 文件是如何生成的？是否又想在自己的项目中拥有这么一份 CHNAGELOG 呢？
你可能会考虑手动生成这些 CHANGELOG 文件，但是手动编写 CHANGELOG 文件不仅费时费力，还容易出错。为解决这一问题，开发者们开发了各种自动化工具，其中 git-chglog 就是一个备受推崇的工具之一。
本文就来给你介绍如何使用 git-chglog 工具自动的生成 CHANGELOG 文件，以提高你项目的可维护性和可阅读性。
企业级 Go 项目+ 云原生项目开发脚手架 OneX 就是用了 git-chglog 工具来自动生成 CHANGELOG 文件。这里，也推荐下 OneX 项目，一个非常优秀的 Go 项目开发、云原生项目开发教学项目。
git-chglog 工具简介
git-chglog 是一个基于 Git 提交记录自动生成 CHANGELOG 文件的工具，它能够根据 Git 提交的信息自动整理生成 CHANGELOG 文件，让开发者无需手动维护版本历史和变更记录。这不仅提高了项目的可维护性和可读性，还节省了开发者的时间和精力。
git-chglog 支持自定义模板和样式，可以根据项目的需求灵活配置生成的 CHANGELOG 文件的格式和内容。同时，它还提供了丰富的命令行选项和配置项，方便开发者根据实际情况进行定制化设置。
使用 git-chglog 工具，开发者可以轻松地生成规范化的 CHANGELOG 文件，让团队成员和用户更加清晰地了解项目的版本发布历史和变更详情。这不仅有助于提升团队协作效率，还能增强项目的可信度和透明度。
git-chglog安装和配置
要使用 git-chglog 工具，首先就要安装 git-chglog 工具。
安装 git-chglog 工具
安装命令如下：
$ go install github.com/git-chglog/git-chglog/cmd/git-chglog@latest
如果你克隆了 OneX 项目，还可以在 OneX 项目根目录下执行以下命令来安装：
$ make tools.install.git-chglog
git-chglog 详细使用方法，可以参考：git-chglog -h：
$ git-chglog -h
USAGE:
git-chglog [命令行选项] <标签查询>
对于<标签查询>，有以下规范方法.
1. <旧标签>..<新标签> - 包含在<旧标签>到<新标签>之间的提交.
2. <标签名>.. - 从<标签名>到最新的标签之间的提交g.
3. ..<标签名> - 从最旧的标签到<标签名>之间的提交.
4. <标签名> - 包含在<标签名>中的提交.
OPTIONS:
--init 在交互模式下生成git-chglog配置文件（默认值：false）
--path value [ --path value ] 按路径过滤提交。可以多次使用.
--config value, -c value 指定要使用的不同配置文件（默认值：".chglog/config.yml"）
--template value, -t value 指定要使用的模板文件。如果未指定，则使用配置文件中的模板
--repository-url value 指定git存储库的URL。如果未指定，则使用配置文件中的'repository_url'
--output value, -o value 更改日志的输出路径和文件名。如果未指定，则输出到标准输出
--next-tag value 将未发布的提交视为指定的标签（实验性功能）
--silent 禁用标准输出（默认值：false）
--no-color 禁用彩色输出（默认值：false）
--no-emoji 禁用表情符号输出（默认值：false）
--no-case 禁用区分大小写的过滤器（默认值：false）
--tag-filter-pattern value 标签过滤的正则表达式。如果指定，只会选择匹配的标签
--jira-url value Jira URL
--jira-username value Jira 用户名
--jira-token value Jira Token
--sort value 指定如何排序标签；目前支持按"date"或"semver"排序（默认值：date）
--help, -h 显示帮助信息
--version, -v 打印版本号
EXAMPLE:
$ git-chglog
If <tag query> is not specified, it corresponds to all tags.
This is the simplest example.
$ git-chglog 1.0.0..2.0.0
The above is a command to generate CHANGELOG including commit of 1.0.0 to 2.0.0.
$ git-chglog 1.0.0
The above is a command to generate CHANGELOG including commit of only 1.0.0.
$ git-chglog $(git describe --tags $(git rev-list --tags --max-count=1))
The above is a command to generate CHANGELOG with the commit included in the latest tag.
$ git-chglog --output CHANGELOG.md
The above is a command to output to CHANGELOG.md instead of standard output.
$ git-chglog --config custom/dir/config.yml
The above is a command that uses a configuration file placed other than ".chglog/config.yml".
$ git-chglog --path path/to/my/component --output CHANGELOG.component.md
Filter commits by specific paths or files in git and output to a component specific changelog.
配置 git-chglog 工具
git-chglog 配置是个 YAML 文件，默认位置为：.chglog/config.yml。可以通过 --config 或 -c 选项，来指定配置文件，例如：
$ git-chglog -c .chglog/config.yml
git-chglog 配置默认保存路径为项目根目录下的 .chglog 目录，内容如下：
$ ls .chglog/
CHANGELOG.tpl.md config.yml
以下是一个config.yml示例配置：
bin: git # 指定 Git 命令的路径。
style: "" # 指定使用的样式文件
template: CHANGELOG.tpl.md # 指定使用的模板文件
info: # 指定生成的 CHANGELOG.md 文件的标题和仓库 URL
title: CHANGELOG
repository_url: https://github.com/superproj/zero
options: # 指定生成 CHANGELOG.md 文件的选项
tag_filter_pattern: '^v' # 指定用于过滤标签的正则表达式
sort: "date" # 指定排序方式，可以是 date、semver 或 keep
commits: # 指定如何过滤和排序提交
filters: # 指定要过滤的提交类型
Type:
- feat
- fix
- perf
- refactor
sort_by: Scope # 指定排序方式，可以是 Scope、Type、Subject、Body 或 Footer
commit_groups: # 指定如何分组提交
group_by: Type # 指定分组方式，可以是 Type、Scope 或 Subject
sort_by: Title # 指定排序方式，可以是 Title 或 Count
title_order: # 指定标题的顺序
- feat
title_maps: # 指定标题的映射
feat: Features
fix: Bug Fixes
perf: Performance Improvements
refactor: Code Refactoring
header: # 指定如何处理提交的头部
pattern: "^(\\w*)(?:\\(([\\w\\$\\.\\-\\*\\s]*)\\))?\\:\\s(.*)$" # 指定用于匹配头部的正则表达式
pattern_maps: # 指定头部的映射
- Type
- Scope
- Subject
issues: # 指定如何处理提交中的问题
prefix: # 定用于识别问题的前缀
- #
refs: # 定用于识别问题的前缀
actions: # 指定用于识别引用的操作
- Closes
- Fixes
merges: # 指定如何处理合并提交
pattern: "^Merge branch '(\\w+)'$" # 指定用于匹配合并提交的正则表达式
pattern_maps: # 指定合并提交的映射
- Source
reverts: # 指定如何处理还原提交
pattern: "^Revert \"([\\s\\S]*)\"$" # 指定用于匹配还原提交的正则表达式
pattern_maps: # 指定还原提交的映射
- Header
notes: # 指定如何处理提交中的注释
keywords: # 指定用于识别注释的关键字
- BREAKING CHANGE
CHANGELOG.tpl.md 模版文件内容如下：
{{ range .Versions }}
<a name="{{ .Tag.Name }}"></a>
## {{ if .Tag.Previous }}[{{ .Tag.Name }}]({{ $.Info.RepositoryURL }}/compare/{{ .Tag.Previous.Name }}...{{ .Tag.Name }}){{ else }}{{ .Tag.Name }}{{ end }} ({{ datetime "2006-01-02" .Tag.Date }})
{{ range .CommitGroups -}}
### {{ .Title }}
{{ range .Commits -}}
* {{ if .Scope }}**{{ .Scope }}:** {{ end }}{{ .Subject }}
{{ end }}
{{ end -}}
{{- if .RevertCommits -}}
### Reverts
{{ range .RevertCommits -}}
* {{ .Revert.Header }}
{{ end }}
{{ end -}}
{{- if .NoteGroups -}}
{{ range .NoteGroups -}}
### {{ .Title }}
{{ range .Notes }}
{{ .Body }}
{{ end }}
{{ end -}}
{{ end -}}
{{ end -}}
生成 CHANGELOG.md 文件
在配置 git-chglog 工具之后，可以使用 git-chglog 命令生成 CHANGELOG.md 文件。git-chglog 提供了多种方式来根据需要生成 CHAGNELOG.md 文件，具体如下。
- 生成所有标签的 CHANGELOG
$ git-chglog -o CHANGELOG.md
生成的 CHANGELOG 内容如下：
<a name="v1.0.0"></a>
## v1.0.0 (2021-07-08)
### Bug Fixes
* fix `make tools` error
* **pkg:** fix the wrong ping path
### Code Refactoring
* **pkg:** add custom logger middleware
* **pkg:** remove default middlewares and rewrite wrktest.sh
* **pkg:** add dump middleware
### Features
* init commit
* **apiserver:** change gorm v1 to v2
* **iamctl:** add nbf for iamctl jwt sign
- 生成包含从
1.0.0到2.0.0提交的 CHANGELOG
$ git-chglog 1.0.0..2.0.0 -o CHANGELOG.md
- 生成包含仅
1.0.0提交的 CHANGELOG
$ git-chglog 1.0.0 -o CHANGELOG.md
- 生成包含最新标签中的提交的 CHANGELOG
$ git-chglog $(git describe --tags $(git rev-list --tags --max-count=1)) -o CHANGELOG.md
- 输出
CHANGELOG.md到标准输出
$ git-chglog
- 使用
.chglog/config.yml配置文件
$ git-chglog -c .chglog/config.yml -o CHANGELOG.md
- 您的支持是我写作的最大动力！如果这篇文章对您有帮助，感谢点赞和关注；
- 强烈推荐我写的一个优秀的 Go + 云原生项目开发脚手架：OneX。可以让你轻松开发 Go 项目，解放双手，提高开发效率！
转载自:https://juejin.cn/post/7363555404131745792