18-迭代日志自动化生成CHANGELOG自动更新、版本内容追溯前言大家好我是黒漂技术佬。你有没有遇到过这种场景版本上线了产品经理问这次更新了啥“你翻了半天 Git 提交记录东拼西凑凑出一个发布说明。更惨的是三个月后老板问v2.3 版本改了哪些东西”——你得重新翻 Git 历史那叫一个痛苦。今天咱们就来解决这个痛点如何让 CHANGELOG 自动生成告别手工整理。一、为什么需要自动化 CHANGELOG先看一个手工版 CHANGELOG 是什么样v2.3.1 更新内容 - 修复了一些 Bug - 优化了部分功能 - 调整了几个页面这种 CHANGELOG 等于没写。真正的变更日志应该是## v2.3.1 (2024-06-15) ### Bug Fixes - **锁控模块**: 修复SPI通信超时导致出货失败的问题 (#4782) - **支付模块**: 修复网络断开后重复扣款的问题 (#4756) ### Features - **扫码模块**: 新增低光照环境下自动补光功能 (#4701) - **后台管理**: 新增设备在线率实时统计面板 (#4710)每一步改动都有据可查、可追溯。工具化是实现这种日志的唯一出路。二、Conventional Commits自动化日志的前提想让工具自动生成 CHANGELOG前提是你的 Commit Message 遵循规范。这就是Conventional Commits约定式提交type(scope): subject [optional body] [optional footer]常用 type 对照表Type说明CHANGELOG 归类feat新功能FeaturesfixBug 修复Bug Fixesdocs文档更新不出现style代码格式不影响逻辑不出现refactor重构不出现perf性能优化Performance Improvementstest测试相关不出现chore构建/工具配置不出现BREAKING CHANGE不兼容变更BREAKING CHANGES示例gitcommit-mfeat(lock): 增加USB转串口驱动的热插拔检测 设备端插入USB转串口模块后无需重启即可自动识别并初始化。 采用udev规则监听设备事件驱动层自动绑定。 Closes #4892这样工具就能自动把这条 commit 归到版本日志的Features分类下。三、实战用 standard-version 一键生成 CHANGELOGstandard-version是目前最主流的自动化版本管理和 CHANGELOG 生成工具。3.1 安装与配置# 项目根目录安装npminstall--save-dev standard-version在package.json中添加脚本{scripts:{release:standard-version,release:minor:standard-version --release-as minor,release:patch:standard-version --release-as patch}}3.2 执行发版# 自动根据 Commit 类型决定版本号升级# feat → minor, fix → patch, BREAKING CHANGE → majornpmrun release# 指定版本号npmrun release:patch# v2.3.0 → v2.3.1npmrun release:minor# v2.3.0 → v2.4.0执行后standard-version会自动做三件事升级版本号更新package.json中的 version 字段生成 CHANGELOG在CHANGELOG.md中追加新的版本日志创建 Git Tag自动git tag v2.3.1生成的CHANGELOG.md大概长这样# Changelog ## [2.3.1](https://git.example.com/compare/v2.3.0...v2.3.1) (2024-06-15) ### Bug Fixes * **lock**: 修复SPI通信超时导致出货失败 ([abc1234](https://git.example.com/commit/abc1234)) * **payment**: 修复重复扣款问题 ([def5678](https://git.example.com/commit/def5678)) ### Features * **scan**: 新增低光照自动补光功能 ([ghi9012](https://git.example.com/commit/ghi9012))3.3 多个仓库怎么办我们团队有 3 个仓库后端微服务、安卓固件、小程序。如果都用 npm 项目每个仓库单独配置即可。对于非 npm 项目比如 Android 固件、纯 Python 项目可以用conventional-changelog直接生成# 不修改package.json只生成CHANGELOGnpx conventional-changelog-pangular-iCHANGELOG.md-s-r0四、CI/CD 集成自动更新 CHANGELOG更进一步我们可以把 CHANGELOG 生成集成到 CI/CD 流程中每次合并到 master 自动触发。.gitlab-ci.yml 示例release:stage:releaseonly:-masterscript:-npm ci-git config user.email ci-botexample.com-git config user.name CI Bot-npm run release-git push--follow-tags origin master这样每次合并到 masterCI 会自动扫描所有 commit 类型确定版本号升级方式生成/更新 CHANGELOG.md打 Tag 并推送五、版本内容追溯从猜到查自动化 CHANGELOG 最大的价值不是看起来好看而是可追溯。有了规范化的 CHANGELOG你可以快速回顾git log v2.3.0..v2.3.1 --oneline一秒定位改动范围关联 Issue每条改动都链接到对应的 Issue/Task形成需求→开发→发布的闭环审计合规客户或监管要求提供某版本改了什么直接发 CHANGELOG 就行季度复盘一看 CHANGELOG 就知道这个季度产出了多少 Feature、修了多少 Bug# 一键查看两个版本之间的所有变更gitlog v2.3.0..v2.3.1--oneline--no-merges六、常见坑与最佳实践Commit 不规范日志就废了——在团队推 Conventional Commits 之前先用commitlint Husky 做提交校验不合规的 commit 直接拒绝不要手动改 CHANGELOG——手动改了下次自动生成会冲突让工具全权管理release commit 也要规范——standard-version生成的 commit 默认是chore(release): 2.3.1不要手动去改它多仓库统一规范——后端 Java 项目、前端小程序、固件 C 项目都要遵守相同的 Commit 规范commitlint 配置示例commitlint.config.jsmodule.exports{extends:[commitlint/config-conventional],rules:{type-enum:[2,always,[feat,fix,docs,style,refactor,perf,test,chore,revert,build,ci]],subject-max-length:[2,always,72]}};总结自动化 CHANGELOG 的核心逻辑很简单规范 Commit → 工具解析 → 自动生成。前期投入一点时间规范团队的提交习惯换来的是永久告别手工整理日志的痛苦。记住一句话**你写的每一条 Commit Message都是写给三个月后的自己看的。**既然要写就写得规范一点。