跳到正文

破坏性变更条目

让现有用户识别受影响的场景,理解变更前后差异,并验证迁移结果。

先让读者判断是否受影响

条目标题写出具体的变化,例如“配置键 indexFile 更名为 search.output”。第一段说明起始版本、影响条件和可见后果。只影响使用特定运行环境、显式配置或旧默认值的项目时,要用能在配置或日志中直接查到的条件描述。

可用下面的顺序起草条目。

  1. 写明哪个版本发生变化,以及读者到哪里检查自己的配置。
  2. 并列展示旧写法、新写法和实际行为的差异。
  3. 给出迁移动作与确认成功的方式。
  4. 说明保留旧环境和数据时的兼容条件。

对齐迁移前后的输入

对象1.x2.x要检查的结果
输出设置indexFilesearch.output生成的索引路径与配置一致
未指定输出路径index.jsonsearch-index.json部署资产和读取端使用相同路径

同一个用户任务的前后配置应使用相同的示例输入,便于看出改了哪些键和行为。以后要迁移的用户也应能找到旧版本的参考。

记录失败路径和恢复条件

升级可能分多步时,明确每一步是否可独立运行。改变存储格式时交代备份、验证、兼容旧版的条件和需要保留的内容。对配置更名的完整写法,可以参考输出配置迁移示例。在发布记录里加上指向具体迁移条目的链接。