Golang模块生成变更日志技巧详解

还在手动编写 Golang 项目的变更日志？效率低且容易出错！本文详解如何使用 `git-chglog` 这一高效、标准化的工具，基于 Git 提交记录自动生成结构清晰的 `CHANGELOG.md` 文件，尤其适合模块版本更新时的文档维护。文章将深入介绍 `git-chglog` 的安装、配置、以及如何遵循 Conventional Commits 规范提交 commit，确保变更内容正确分类。更重要的是，我们将探讨如何通过命令快速生成 CHANGELOG.md 文件，并结合 CI/CD 自动化流程，显著提升 Golang 模块的版本发布效率。告别繁琐的手动编写，拥抱自动化变更日志生成，让你的 Golang 项目文档维护更加轻松！

git-chglog 是一款基于 Git 提交记录生成结构化变更日志的工具，适用于 Golang 项目。1. 安装 git-chglog 可通过 go install 命令快速完成；2. 初始化配置文件后可自定义模板与配置；3. 需遵循 Conventional Commits 规范提交 commit 以确保正确分类；4. 通过命令生成 CHANGELOG.md 文件并可结合 CI/CD 自动化流程使用，提升版本发布效率。

为 Golang 模块生成变更日志，使用 git-chglog 是一个高效、标准化的做法。它能基于 Git 提交记录自动生成结构清晰的 CHANGELOG.md 文件，适合用于模块版本更新时的文档维护。

什么是 git-chglog？

git-chglog 是一个开源工具，专门用来从 Git 的 commit 中提取信息，并按照指定格式生成变更日志（CHANGELOG）。它支持多种模板风格，也允许你根据项目规范进行自定义。相比手动编写 changelog，它更自动化、统一，也更容易集成进 CI/CD 流程中。

如何在 Golang 项目中集成 git-chglog

1. 安装 git-chglog

最简单的方式是通过 go install 安装：

go install github.com/git-chglog/git-chglog/cmd/git-chglog@latest

安装完成后，可以通过运行 git-chglog --version 验证是否成功。

2. 初始化配置文件

在项目根目录下执行以下命令来生成默认配置文件：

git-chglog --init

这个命令会在当前目录创建 .chglog 目录，里面包含默认的配置文件和模板。主要关注的是 config.yml 和 default.tpl。

你可以根据需要修改模板内容，比如添加图标、调整标题层级等。

3. 按照约定提交 commit

git-chglog 默认识别 Conventional Commits 规范的提交信息。例如：

• feat: 新增功能
• fix: 修复 bug
• docs: 更新文档
• chore: 构建或辅助工具改动

这类格式能让 git-chglog 正确分类变更内容并归类到对应章节。

如果你已经有历史提交但不符合规范，可以考虑先整理最近几次关键提交，或者使用 --sort 参数让工具自动归类。

4. 生成 CHANGELOG.md

在每次发布新版本前运行以下命令：

git-chglog -o CHANGELOG.md

这会根据最新的 Git 提交记录生成或更新 CHANGELOG.md 文件。

如果你想只生成某个版本的变更记录，可以用：

git-chglog v1.0.1 > CHANGELOG_v1.0.1.md

常见问题与建议

• 生成内容为空？
  确保你的 commit 符合 Conventional Commits 规范，否则可能无法被识别。也可以检查 .chglog/config.yml 中的 filter_commits 设置是否过于严格。

• 不想每次都手动运行怎么办？
  可以将 git-chglog 集成进你的 CI/CD 流水线，比如 GitHub Actions，在 tag 推送后自动更新 changelog 并提交 PR 或直接推送到主分支。

• 想按不同类别分组展示？
  修改模板文件即可实现。例如，把 feat 放在 Features 小节，fix 放在 Bug Fixes 小节，这样视觉上更清晰。

• 如何配合 semver 使用？
  git-chglog 本身不处理语义化版本号，但你可以结合 git tag 来标记版本，再用 git-chglog 生成对应版本的 changelog。

示例：GitHub Actions 自动化流程

下面是一个简单的 GitHub Action 工作流，用于在打 tag 后自动生成 changelog 并提交：

name: Generate Changelog

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Install git-chglog
        run: go install github.com/git-chglog/git-chglog/cmd/git-chglog@latest

      - name: Generate changelog
        run: git-chglog -o CHANGELOG.md

      - name: Commit and push changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add CHANGELOG.md
          git commit -m "docs: update changelog for ${{ github.ref }}"
          git push origin HEAD:${{ github.ref }}

基本上就这些。用好 git-chglog 的关键是规范 commit 格式 + 合理配置模板。虽然步骤看起来不多，但很容易因为格式不一致导致输出结果不如预期，所以建议团队内部统一 commit 规范。

到这里，我们也就讲完了《Golang模块生成变更日志技巧详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！