AI 生成发布说明：别把 Commit 列表直接发给用户

AI 生成发布说明：别把 Commit 列表直接发给用户

独立产品更新频繁，发布说明很容易被忽略。AI 可以根据 commit、issue、PR 自动生成 changelog，但如果只是把提交列表翻译成中文，用户依然看不懂。用户关心的是：我能做什么新事？什么问题被修了？有没有需要我注意的变化？

发布说明不是给代码仓库看的，而是给用户和团队看的。

一、先把变更分类

flowchart TD
  A[Commits And Issues] --> B[Feature]
  A --> C[Fix]
  A --> D[Improvement]
  A --> E[Breaking Change]
  B --> F[Release Notes]
  C --> F
  D --> F
  E --> F

AI 生成发布说明前，要先把变更按用户影响分类。refactor form state 对用户不是信息，表单填写时不再丢失草稿 才是信息。

分类不能只看 commit message 的 prefix（如 feat: fix:），还要理解变更对用户的真实影响。我们总结了几条分类规则：

1. Feature：用户能做以前不能做的事。如"支持 CSV 导入联系人"
2. Fix：修复了用户能感知到的错误。如"修复 Safari 下导出 PDF 为空的问题"
3. Improvement：没加新功能也没修 bug，但体验变好了。如"列表筛选后记住选中项"
4. Breaking Change：用户需要主动适配的变化。如"导出字段 created_at 改为 createdAt"
5. Internal：用户完全感知不到的变化。如"升级 React 版本"、"重构 API 层"。这类变化不放入发布说明。

AI 在分类时容易把 refactor 标记为 Improvement。需要明确告诉模型：用户感知不到的变化不应出现在发布说明里。

Release notes 分类 AI Prompt：
给定以下 commit 列表和 issue 列表，将每个变更归类到以下类别之一：
- feature: 用户能做新的事情
- fix: 修复了用户能感知的问题
- improvement: 没加功能也没修 bug，但体验变好
- breaking: 用户需要适配
- skip: 用户完全感知不到
输出时只保留前四类，skip 的不输出。

这类 Prompt 能把"重构了表单校验"正确归类为 skip，而把"表单保存前不再误报格式错误"归为 fix。虽然它们可能来自同一次重构，但对用户来说只有后者有意义。

二、Commit 需要转成用户语言

commit: fix debounce in search box
release note: 搜索输入时结果不再频繁闪烁，弱网下体验更稳定。

这一步很适合 AI 做初稿，但人要检查是否夸大。发布说明不能把内部重构包装成新功能。

转换的常见陷阱有：

模糊词陷阱：优化、改善、调整 —— 这类词只说了动作，没说效果。每条 release note 都应该回答"用户能感受到什么变化"。

过度承诺陷阱：大幅提升性能、显著优化体验 —— 如果给不出量化数据，就不要用这种表述。

假新功能陷阱：把重构或技术债务清理包装成新功能。重构路由模块 不能写成"全新的导航系统"。

一个好用的转换模板：

模板：
  commit: {原始提交信息}
  issue: {关联的问题编号，如果有}
  用户视角：{一句话，描述用户感受到的变化}
  影响范围：{这个变化影响哪些功能或页面}
  需要适配：{是否需要用户操作，如果需要，怎么操作}

这个模板能帮助 AI 生成一致且有结构的发布说明。人工 review 时只需要检查"用户视角"是否准确、不夸大。

示例：
  commit: fix: add loading state to export dialog
  issue: #342
  用户视角：导出报表时现在会显示处理进度，不再出现"点了导出没反应"的情况。
  影响范围：所有报表页面的导出功能
  需要适配：无需操作

三、破坏性变更要单独标红

如果接口、配置、导出格式或用户流程有变化，就要明确写出影响和迁移方式。

### 需要注意
- 导出的 CSV 字段 `created_at` 改为 `createdAt`。
- 如果你依赖旧字段名，请在 7 月 10 日前完成适配。

独立产品更需要珍惜用户信任。不要把影响用户工作的变化藏在"优化若干体验"里。

破坏性变更的发布说明要包含四个要素：变什么、影响谁、怎么改、截止日期。缺少任何一个，用户都可能踩坑。示例：

### 破坏性变更
> **API v2 → v3**  
> 变更内容：`GET /api/tasks` 响应中 `dueDate` 字段类型从 `string` 改为 ISO 8601 datetime  
> 影响用户：所有使用旧版 API 的集成用户  
> 迁移方式：在请求头中加 `Accept-Version: 3` 后会返回新格式；旧格式将在 2026-08-01 移除  
> 如有疑问：联系 support@example.com

结构化的破坏性变更说明更容易生成、更容易阅读。可以把这个结构做进 AI Prompt 中，让生成结果自动包含这四个字段。

还要在发布说明的最顶部加一个概览区域，让用户 5 秒内判断这个版本和自己有没有关系：

## v2.4.0 (2026-07-03)
- 新增：批量导出报表
- 修复：移动端列表加载卡顿
- 注意：API 字段名有变更，请查看[迁移文档](link)

这个概览可以由 AI 根据正文自动生成，适合放进应用内弹窗这种短场景。

四、发布说明也要可追溯

AI 生成的每条说明最好能关联 issue、PR 或 commit。内部排查时可以回到来源。

{
  "note": "搜索结果加载更稳定",
  "source": ["PR-128", "issue-77"],
  "type": "fix"
}

这样既方便审稿，也方便后续复盘。

发布说明还要分渠道。应用内弹窗、邮件、文档站、GitHub Release 的读者不一样，文字密度也不一样。AI 可以基于同一份变更生成多个版本。

release_channels:
  in_app: "short and user focused"
  email: "benefit plus links"
  github: "technical details and references"
  docs: "migration guide"

不要把一份长 changelog 复制到所有地方。沟通也需要适配场景。

具体来说，不同的渠道需要不同的长度和重点：

• 应用内弹窗：3 条以内，每条一行，附带"查看详情"链接
• 邮件：重点功能 + 用户收益 + Call to Action（如"立即体验"）
• GitHub Release：完整列表 + 技术细节 + 关联 PR 链接
• 文档站：完整的迁移指南和变更对比

渠道生成约束（AI Prompt）：
应用内弹窗：最多 3 条，每条不超过 30 字，必须有链接到完整说明
邮件：开头一句话总结，展开 2-3 条重点变更，附 Call to Action
GitHub：包含所有非 skip 变更，每条附带来源 PR 链接
文档：包含迁移步骤和前后对比

五、总结

AI 生成发布说明时，要把 commit 和 issue 转换成用户能理解的变化，按 feature、fix、improvement、breaking change 分类，并保留来源追踪。

别把 Commit 列表直接发给用户。好的发布说明，是产品沟通的一部分。

如果用户看完发布说明知道自己该不该升级、会受到什么影响、能获得什么改善，这份说明才算完成任务。

发布说明也要避免过度承诺。比如"显著提升性能"不如写"列表首次加载减少约 300ms"。能量化就量化，不能量化就写清具体变化。用户不需要被营销，他们需要判断这次更新和自己有没有关系。

bad: 大幅优化体验
better: 表格筛选后不再回到第一页

越具体，越可信。

发布说明写得清楚，也能反过来逼团队把需求、缺陷和 PR 关系整理清楚。沟通质量和工程质量经常是连在一起的。