用 AI 根据代码变更编写发布说明：从冻结提交范围到发布负责人批准

要用 AI 根据代码变更编写发布说明，先冻结上一版和当前版的发布边界，建立已核验的变更账本，并把用户影响与实现细节分开。只给 AI 已批准的证据，要求每条说明都能对应到拉取请求、commit、Issue、测试或文档。最终文本由发布负责人对照实际交付物核对。

本流程产出面向用户的发布沟通，而非 commit 摘要。如何使用 AI介绍了安全的输入方式，用 AI 辅助编码和复核 AI 生成代码则涉及实现工作。发布说明要在变更边界和证据明确后才开始写。

关键要点

• 起草前冻结上一版和当前版的确切 tag 或 commit。
• 建立账本，区分代码证据与已核验的用户影响。
• 不要根据文件名、diff 大小或 commit 标题推断行为。
• 统一把变更归为新增、变更、修复、安全、弃用或移除。
• 明确写出迁移、已知问题和披露限制。
• 要求发布负责人对照实际交付物和版本批准。

冻结发布边界

确定要描述的确切交付物及其替代的交付物。记录代码库、产品或组件、上一版本或 commit、当前版本或 commit、构建标识、目标渠道和发布日期。main 这类分支名不是稳定边界，起草期间它可能还在移动。

尽量使用不可变的 tag 或完整 commit 标识。一次发布由多个代码库组成时，为每个代码库记录边界，并指出连接它们的组成清单或构建记录。部署的交付物与计划的 tag 不一致时，停下来解决。

GitHub Releases 把说明和资源关联到某个 tag，能把发布与普通代码库历史区分开。［2］ GitHub 还能根据两个 tag 间合并的拉取请求和贡献者自动生成发布说明。［1］ 这些是有用的输入，但本身不能证明哪些行为真正到达用户，也不能证明拉取请求标题描述准确。

验收标准也要冻结：定义受众、支持的升级路径、分发渠道，以及什么算用户可见。内部重构可以不写；默认值变化、新权限、移除字段或运维要求，即使 diff 很小也可能必须写入。

建立变更证据账本

写正文前，每条候选说明先占一行：

版本	Commit 范围	PR 或 commit	关联 Issue	用户可见行为	Breaking	Migration	Security	Deprecation	测试证据	文档	负责人
x.y.z	[base..head]	[不可变 ID]	[Issue ID]	[已核验行为]	是/否/未知	[步骤或无]	公开/私密/无/未知	[时间线]	[命令与结果产物]	[页面]	[姓名]

PR 或 commit 和关联 Issue 从代码库记录填写，但结果要在代码、测试、文档或构建出的产品中核验。已合并的提议可能被部分回退；Issue 描述的可能是最初问题而非最终方案。

用户可见行为应回答：谁会注意到、在何种条件下、改了什么、需做什么。“重构了缓存层”是实现细节；“重复请求现在会在五分钟内复用有效缓存结果”是行为主张，仍需证据。

测试证据须写明命令、环境、相关输出和日期。说不清是哪些测试、针对哪个 commit、失败项是否被跳过时，“测试通过”就不够。让环境缺口保持可见；本地成功不等于生产环境成立。

如何从证据判断用户影响？

阅读实际的 diff、变更的契约、迁移、配置、功能开关和文档。变更间接影响行为时，追踪入口点和调用点。数据或 API 变更要检查兼容性、默认值、序列化和升级顺序。

不要根据文件名推断行为。名为 fix_login.py 的文件不能证明登录问题已修复。很大的 diff 可能只是重新格式化生成的代码，一行默认值改动却可能影响每个请求。commit 标题和标签是索引工具，不是证据。

每条候选说明至少需要一个行为层面的来源：验收测试、重现的前后对比、已批准的规格、可观察的契约变更或人工验证记录。实现证据可作支持附上，但不能代替面向用户的主张。

行为未核验时标为“未知”，解决前不写进公开说明。不要把开发者的预期变成面向客户的事实。藏在关闭的功能开关后的计划功能不算普遍可用。

变更应该如何统一分类？

使用受控的分类体系：

• 新增（Added）： 新提供的用户能力。
• 变更（Changed）： 现有行为、默认值、流程或要求有变。
• 修复（Fixed）： 已核验的缺陷在所述条件下不再重现。
• 安全（Security）： 按披露政策处理的安全相关变更。
• 弃用（Deprecated）： 仍可用，但已有移除或替代路径。
• 移除（Removed）： 不再提供。

把分类与语义化版本的决定分开。语义化版本规范针对已声明的公共 API 定义了主、次和补丁版本的变化，包括不兼容的变更和向后兼容的功能或修复。［3］ 产品可采用别的方案，但应写明版本号承诺什么。

不要只因改了很多文件就称为“破坏性变更”。检查公共契约、持久化数据、配置、自动化、受支持的客户端和运维流程。反之，新增必填字段或修改默认值，即使能编译通过，也可能是破坏性的。

弃用说明须写明受影响的接口、替代方案、首次弃用版本、预计移除的版本或条件和迁移指引。只写“弃用旧端点”而无后续路径，毫无用处。

用 AI 根据代码变更编写发布说明前准备受限证据包

准备有边界的证据包，含发布边界、已批准的账本行、受众和风格指南、以往术语及要求的输出结构。排除秘密、凭证、私人客户数据、敏感日志、禁发期内的漏洞细节和无关源代码。

不要把整个代码库不加限制地交给 AI，问“改了什么？”。模型可能偏重易读的文件，漏掉生成或配置带来的行为，或凭名称推断意图。账本应先由人和确定性工具建立。

一条可复用的提示词是：

只用已批准的账本行起草发布说明。保留确切的版本、受众、条件、迁移步骤、已知限制和证据 ID。不要根据文件名、commit 标题、标签或 diff 大小推断行为。该行无验证证据时，不要声称已修复。分开写新增、变更、修复、升级/迁移、已知问题和安全披露边界。用户影响为“未知”时，省略该主张，并为发布负责人列出证据缺口。

写正文前，要求先给出可追溯表：

说明 ID	草稿陈述	账本行	受众	必需动作	验证状态
RN-01	[有边界的面向用户陈述]	CH-04	管理员	[步骤或无]	已核验

否决合并不相关账本行或扩大范围的说明。修好一个边界情况，未必推得出“可靠性提升”；“更快”也需要明确指标和实测对比。

怎样面向用户而不是 diff 起草？

先写目标读者认得出的结果，写明受影响的功能、条件和需采取的行动。除非类名属于受支持的公共接口，否则不写内部类名。

写“重新打开导出文件时，现在会保留所选时区”，而非“更新了序列化器的时区处理”。描述修复时，写出之前的症状及在什么条件下不再出现。不要透露不必要的利用细节，也不要承诺相关故障都不会再发生。

使用这样的结构：

1. 亮点： 少量重要、已核验的结果。
2. 变更： 新增、变更、弃用和移除的行为。
3. 修复： 已核验的缺陷及其边界条件。
4. 升级/迁移： 前提、顺序、备份和验证。
5. 已知问题： 已确认的限制和安全的变通办法。
6. 安全披露边界： 现在能说什么，获批的安全公告在哪里发布。

并非每次发布都需要所有章节。空类别不出现在公开说明里，但在账本中保留其复核状态，让“没有”是刻意的而非遗漏。

核验升级与迁移

迁移说明应可照着执行：写明谁必须操作、适用哪些起始版本、按什么顺序、需要哪些权限，以及如何确认成功。备份和回滚指引只在经测试且受支持时提供。

区分应用迁移、数据库迁移、配置改名、客户端升级和运维重启。推出期间新旧版本并存时，说明兼容性限制。不清楚安全顺序时，停止发布，向负责人取得指引。

绝不能编造回滚方法。有些数据转换不可逆，有些安全变更也不应轻易回滚。写明已批准的恢复途径和升级联系人，而非编一条令人安心的命令。

AI 生成测试流程只能作为另一项经复核的工程活动。生成的测试只有针对冻结版本运行、且有人确认其确实测试了所称行为后，才算证据。

公开发布说明里能写多少安全细节？

与安全和发布负责人协调安全措辞。公开说明可以写“依赖项或防护已更新”，但详细漏洞信息可能需要单独的安全公告、协调好的披露日期或针对特定客户的沟通。

不要把秘密、利用步骤、私下报告或未公布的漏洞细节粘贴进外部模型，也不要让 AI 决定严重程度、可利用性、受影响版本或披露时间。这些是高度依赖证据、由负责的人作出的决定。

NIST 的生成式 AI 风险概况强调虚构、隐私、信息完整性和人工监督等风险。［4］ 有边界的证据包、逐条主张的可追溯性、访问控制和发布负责人批准，正是在此直接应对这些风险。

“安全披露边界”一节应说明公开说明刻意包含什么、哪些留给获批的安全公告，以及由谁批准这一划分。沉默不应让人误以为没做过任何安全相关工作。

对照实际交付物复核

逐行对照确切的发布交付物复核草稿，而不只是对照源代码分支。确认版本字符串、功能开关、打包的依赖、迁移文件、文档链接和支持的平台。打包可能排除某项变更时，核验安装包本身。

检查清单：

• base 和 head 标识与交付物一致；
• 每条说明都对应到已批准的账本行；
• 用户可见行为经过演示，而非推断；
• 版本和分类标签遵循产品政策；
• 迁移步骤、顺序和恢复方法已核验；
• 已知问题只含已确认的限制；
• 安全措辞遵循披露决定；
• 测试写明实际命令、环境和结果；
• 链接和特定版本文档在本地可解析；
• 发布负责人批准了确切的最终文本。

需要发布负责人批准，是因为负责人了解打包、推出和披露的背景；作者或模型无法单凭 diff 推断。

发布后维护说明

把已批准的账本、提示词输入、草稿和最终说明随发布记录归档。某项主张需要更正时，发布带日期的更正，而非悄悄改写历史，并保留改了什么及原因。

新 commit 进入发布时，原边界即失效。为新范围重新生成候选账本，找出新增和受影响的说明，重新验证并再次取得批准。不要在已复核的草稿后追加一句猜测。

发布后复核反馈。用户的问题可能暴露迁移步骤不清、条件缺失或用户不认识的术语。改进以后的模板，但每份历史说明都与其实际发布的版本绑定。

常见问题

可以直接从 Git 历史生成发布说明吗？

它能生成候选清单，但仅凭历史无法证明用户影响或实际发布的行为。公开起草前，先建立并核验变更账本。

GitHub 自动发布说明够用吗？

它适合列出两个 tag 间合并的工作；发布负责人仍需核验交付物、受众、行为、迁移、已知问题和披露边界。

每个 commit 都要公开吗？

不需要。只写重要的用户可见行为和必需的运维行动；内部可追溯性另存，供审计和调试。

如何安全描述缺陷修复？

写出观察到的症状、受影响条件和已核验的结果。除非证据支持，不要声称整类问题都不会再出现。

变更没有测试怎么办？

使用其他已批准的行为层面验证，或标为未核验；不要把开发者意图当作已确认的发布结果。

AI 能选择语义版本号吗？

它可依据书面政策整理证据，但公共契约是否变化，须由发布负责人判断并批准版本号。

安全修复要公开吗？

遵循已批准的披露流程。公开措辞、时间、受影响版本和技术细节，都需安全和发布负责人复核。

Commit 范围变化怎么办？

冻结新范围，重建受影响的账本行，重查每条说明并再次取得批准。之前的草稿已不再描述这个确切的交付物。

来源

1. GitHub Docs, Automatically generated release notes — https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
2. GitHub Docs, About releases — https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
3. Semantic Versioning 2.0.0 — https://semver.org/
4. National Institute of Standards and Technology, Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile — https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence

Sources checked 2026 年 8 月 30 日。