变更日志必须基于 Git 提交历史生成，而非 Go Modules 版本号；需校验 tag 与 go.mod 一致，用 conventional commits 规范提交，提取 feat/fix 等类型并标注破坏性变更，同时输出 JSON 等多格式供集成。
变更日志生成必须基于 Git 提交历史，而非 Go Modules 版本号
Go Modules 的 go.mod 里 require 行只记录依赖版本（如 v1.2.3），不包含变更内容。直接解析它无法生成有意义的日志。真正可信赖的来源是 Git 的提交记录——每个 git commit 带有作者、时间、消息和 diff，这才是变更的原始凭证。
常见错误是试图用 go list -m -u -json all 或 go mod graph 推导“改了什么”，结果只能得到版本升降，完全丢失功能描述、修复项、破坏性变更等关键信息。
- CI 流水线中应在构建前拉取完整 Git 历史（
git fetch --depth=0），确保能访问所有 tag 和 commit - 必须校验当前 HEAD 是否已打 tag：用
git describe --exact-match --tags HEAD判断是否为发布点 - 若未打 tag，变更日志应基于上一个 tag 到 HEAD 的区间生成（
git log v1.2.0..HEAD --oneline） - 跳过 merge commit（
--no-merges），避免日志混入无关的集成噪音
用 conventional commits 规范提交消息，才能自动提取类型和范围
没有结构化的提交消息，任何自动化工具都只能做关键词匹配（比如搜 “fix”、“feat”），极易误判。Conventional Commits 是事实标准：以 type(scope): subject 开头，例如 feat(auth): add JWT token refresh 或 fix(api): prevent panic on empty request body。
CI 中可用 git log --format="%s" $FROM..$TO 提取标题行，再用正则或专用工具（如 conventional-changelog CLI）分类归并：
立即学习“go语言免费学习笔记（深入）”；
-
feat→ “新功能”章节，fix→ “问题修复”，chore/refactor通常不放入用户可见日志 - scope（如
auth、db、cli）可用于分组，避免所有条目堆在一行 - 提交正文（body）中若有
Breaking Changes:段落，必须单独提取并标为 ⚠️ 破坏性变更 - 避免依赖 GitHub/GitLab 的 PR 标题——CI 运行时 PR 可能尚未合并，且标题常不规范
生成日志时必须绑定 Go Modules 版本与 Git tag，否则语义失效
变更日志本质是“从 A 版本到 B 版本之间发生了什么”。如果 Git tag（如 v1.5.0）和 go.mod 中声明的模块版本（module github.com/your/app v1.5.0）不一致，读者会彻底困惑：到底该信哪个？
实操中必须强制两者同步：
- 发布前运行校验脚本：
git tag | grep "^v" | xargs -I{} sh -c 'grep -q \"module .* {}\" go.mod || echo "tag {} mismatch go.mod"' - CI 中在打包前执行
go mod edit -module github.com/your/app/v2（如需大版本升级），再打对应 tagv2.0.0 - 生成日志的命令（如
conventional-changelog -p angular -i CHANGELOG.md -s）应明确指定--from和--to为 Git tag，而非任意 commit hash - 最终产物（二进制、Docker 镜像）的元数据中应同时嵌入 Git commit hash 和 Go Modules version，便于追溯
不要把 CHANGELOG.md 当作唯一输出，需适配多场景消费
纯文本 CHANGELOG.md 对人友好，但 CI/CD 流程、监控系统、前端展示往往需要结构化数据。硬编码生成 Markdown 会卡死后续集成。
推荐在流水线中一步生成多种格式：
- 用
conventional-changelog的--output输出 JSON 格式（如changelog.json），含version、date、features、fixes字段 - 将 JSON 注入 Docker 镜像
LABEL：docker build --build-arg CHANGELOG_JSON="$(cat changelog.json | jq -r tostring)" ... - HTTP 服务启动时读取
changelog.json，暴露/health/changelog端点供运维查询 - 避免在 Go 代码里硬编码日志内容——它不属于业务逻辑，也不该随二进制一起编译
最易被忽略的是时间戳精度：Git tag 创建时间和 go mod 版本发布时间可能差数分钟，而变更日志的 date 字段应取 tag 的 annotated commit 时间（git show -s --format=%aI v1.5.0），不是 CI job 启动时间。
