先让读者判断是否受影响
条目标题写出具体的变化,例如“配置键 indexFile 更名为 search.output”。第一段说明起始版本、影响条件和可见后果。只影响使用特定运行环境、显式配置或旧默认值的项目时,要用能在配置或日志中直接查到的条件描述。
可用下面的顺序起草条目。
- 写明哪个版本发生变化,以及读者到哪里检查自己的配置。
- 并列展示旧写法、新写法和实际行为的差异。
- 给出迁移动作与确认成功的方式。
- 说明保留旧环境和数据时的兼容条件。
对齐迁移前后的输入
| 对象 | 1.x | 2.x | 要检查的结果 |
|---|---|---|---|
| 输出设置 | indexFile | search.output | 生成的索引路径与配置一致 |
| 未指定输出路径 | index.json | search-index.json | 部署资产和读取端使用相同路径 |
同一个用户任务的前后配置应使用相同的示例输入,便于看出改了哪些键和行为。以后要迁移的用户也应能找到旧版本的参考。
记录失败路径和恢复条件
升级可能分多步时,明确每一步是否可独立运行。改变存储格式时交代备份、验证、兼容旧版的条件和需要保留的内容。对配置更名的完整写法,可以参考输出配置迁移示例。在发布记录里加上指向具体迁移条目的链接。