发布说明是什么
平台的 Release 把标签、说明与制品绑定在一起，是发布说明最常见的载体。自动生成能根据提交与合并请求给出初稿，但机器生成的表述通常只是罗列标题；发布前仍需人工补充升级注意事项、破坏性变更与已知问题。发布说明的读者是升级方，不是提交者。
基本信息
| 载体 | GitHub / GitLab 的 Release，关联一个标签 |
|---|---|
| 内容 | 新增、修复、破坏性变更、升级步骤、已知问题 |
| 制品 | 可附加构建产物与校验信息 |
| 自动生成 | gh release create <标签> --generate-notes |
| 发布前处理 | 自动生成为草稿，需人工核对与改写 |
典型使用场景
- 每次发版打标签时同步发布说明，方便使用方判断是否升级
- 单独列出破坏性变更与迁移步骤，减少升级方试错
- 附上构建制品与校验信息，便于验证下载完整性
- 写明已知问题与规避方式，降低重复报障
- 从提交历史生成初稿，省去整理清单的时间
常用示例
常用示例
gh release create v2.4.0 --generate-notes # 自动生成发布说明草稿
gh release create v2.4.0-rc1 --prerelease --generate-notes # 预发布版本单独标记
gh release view v2.4.0 # 查看已发布的说明内容
git tag -a v2.4.0 -m 'release 2.4.0' # 创建附注标签作为发布点
git push origin v2.4.0 # 推送标签到远端内容要点
| 章节 | 写给谁看 | 要点 |
|---|---|---|
| 新增能力 | 使用者 | 一句话说清能做什么 |
| 修复列表 | 受影响用户 | 附上关联问题编号 |
| 破坏性变更 | 升级方 | 必须给出迁移步骤 |
| 已知问题 | 运维与支持 | 说明影响范围与规避方式 |
自动生成的内容只是草稿起点，发布前要统一口径并核对链接，避免把内部重构的标题原样发给使用方。
发布说明与变更日志如果各维护一份，两份很快就不一致；让其中一个作为唯一来源，另一个由它生成更省事。
发布之后把说明链接固定下来，出现问题时可以直接把链接发给使用方；临时在聊天里口述升级步骤，事后很难再找到一致的说法。