项目指南

GitHub Release Notes 模板:写清版本变化和升级步骤

好的版本说明应让用户知道是否值得升级,以及下一步怎么做。已合并 Pull Request 列表是有用依据,但通常不能完整说明升级体验。发布前需要补上对用户的影响和必要操作。

GitHubStart 内容团队 · 更新于

从面向用户的版本说明模板开始

把所有方括号字段替换成核实过的信息,删除不适用的章节,不要虚构功能。如果不需要额外升级操作,也应在验证支持的升级路径后明确说明。

# [版本] — [发布日期]

## 重点变化
- [用户可见的改进,以及谁会受益]

## 升级
- 起始版本:[支持的旧版本]
- 操作:[必需迁移步骤,或无需操作]
- 验证:[如何确认升级成功]

## 破坏性变更
- [变化、受影响用户、迁移文档链接]

## 修复
- [已解决问题及 Issue 或 Pull Request 链接]

## 已知问题
- [剩余限制和临时解决办法]

## 贡献者
[感谢贡献者,并链接完整变更日志]

把自动生成记录整理成读得懂的说明

GitHub 可以生成包含已合并 Pull Request、贡献者和完整变更日志链接的版本说明。把它当作草稿,先检查版本范围,再移除无关条目,并按用户实际执行的任务归类。

例如,“修复解析器边缘情况”很难指导用户。如果符合事实,可以说明“最后一列为空的 CSV 文件现在可以正常导入”,并链接技术细节。只修复了一种情况时,不要声称解决了所有解析问题。

发布公告前验证升级路径

从受支持的旧版本尝试文档中的升级步骤,检查下载链接,并确保文档对应当前发布版本。区分预览版与稳定版,让剩余限制容易被发现。

先发布版本信息,再在社区帖子里链接它。对外公告聚焦一项有意义的改进,版本说明则保留详细依据。收集后续问题,必要时澄清操作说明。

常见问题

Release Notes 和 Changelog 一样吗?

两者有重叠。Changelog 记录随时间发生的变化;Release Notes 解释某次发布及其对用户的影响。可以互相链接,方便读者查看概览与细节。

能直接发布自动生成的版本说明吗?

应先检查。自动生成的 Pull Request 标题可能没有包含迁移步骤、用户影响或已知问题。

每个小代码改动都要写进重点变化吗?

不需要。重点变化留给对用户有意义的改进,详细技术历史放在链接的变更日志里。

参考资料