版本发布说明自动生成需以规范化提交（如Conventional Commits）为输入基础，通过conventional-changelog或changesets等工具提取结构化变更，绑定语义化版本推算流程，在打tag前生成多模板输出（如CHANGELOG.md、RELEASE_NOTES.md及API描述），确保数据一致、可验证、适配多角色。

版本发布说明自动生成，核心是把“人写的变更记录”变成“机器可读、可聚合、可验证的结构化输出”。它不是简单拼接 commit，而是依赖规范化的输入、可靠的提取逻辑和可配置的模板。

提交信息必须遵循约定式规范

自动提取的前提是输入有章可循。推荐采用 Conventional Commits 标准，每条提交以类型前缀开头：

• feat: 新增功能 → 触发 MINOR 版本升级，计入“新特性”章节
• fix: 修复缺陷 → 触发 PATCH 升级，归入“问题修复”
• chore: 构建或 CI 配置调整 → 默认不写入用户版发布说明，但可进内部日志
• docs: 文档更新 → 可选展示在“文档更新”小节，不影响版本号

工具如 commitlint 可在 pre-commit 或 CI 阶段拦截不合规提交，确保源头数据干净。

从 Git 历史中可靠提取变更内容

发布说明本质是两个 tag 之间的差异摘要。主流做法是基于 git log + 解析器生成：

• 使用 conventional-changelog 系列工具（如 conventional-changelog-cli），配合配置文件指定解析规则与模板路径
• 在 CI 流水线中执行：conventional-changelog -p angular -i CHANGELOG.md -s，自动追加本次 release 的条目
• 若项目用 changesets（如 LogicFlow），则变更描述由 PR 提交者填写 YAML 文件，比纯 commit 更精准、更可控

发布说明需适配不同受众与渠道

同一份变更，面向开发者、终端用户、运维人员的关注点不同，自动化流程应支持多模板输出：

• CHANGELOG.md：完整技术细节，含 PR 编号、作者、关联 issue，供开发者查阅
• RELEASE_NOTES.md：精简版，去除内部构建项，突出用户可见变化，用于 GitHub Release 页面
• GitLab / GitHub Release API 调用时的 description 字段：限制长度（如 2000 字符），只保留高亮项+链接，由脚本截断并注入超链接

与版本号管理深度联动

发布说明不是孤立产物，必须和语义化版本号同步推进：

• 版本号由工具自动推算（如 changeset version 或 semver.inc()），而非人工修改 pyproject.toml 或 package.json
• 生成 CHANGELOG 的动作应绑定在“确定版本号之后、打 tag 之前”的环节，确保日志与 tag 严格对应
• GitHub Actions 或 GitLab CI 中，tag 推送触发 release job，该 job 必须读取已生成的 CHANGELOG 片段，而非重新计算——避免两次解析导致不一致