如何为你的项目生成 CHANGELOG，以提高项目的可维护性？

最新推荐文章于 2024-07-25 14:12:59 发布

孔令飞

最新推荐文章于 2024-07-25 14:12:59 发布

阅读量1.2k

点赞数 21

分类专栏：孔令飞的云原生实战营（知识星球）文章标签： golang kubernetes 云原生

本文链接：https://blog.csdn.net/lnxfei/article/details/138409184

版权

孔令飞的云原生实战营（知识星球）专栏收录该内容

18 篇文章 0 订阅

订阅专栏

大家好，我是孔令飞，字节跳动云原生开发专家、云原生实战营知识星球星主。欢迎关注我的公众号【令飞编程】，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 + 云原生高级开发工程师

孔令飞

关注

21
点赞
踩
10

收藏

觉得还不错? 一键收藏
0
评论
如何为你的项目生成 CHANGELOG，以提高项目的可维护性？

为了提高项目的可维护性和可读性，很多优秀的Go项目会在根目录下添加CHANGELOG.md文件或CHANGELOG目录。这些文件清晰记录了每个版本的变更，让你轻松了解项目的发布历史。本文将介绍如何使用git-chglog工具自动生成CHANGELOG文件，提升项目的可维护性和可读性。
复制链接

扫一扫

专栏目录