跳到正文

编写升级指南

说明适用版本、破坏性变更、迁移顺序和验证结果。

标明从哪个版本升级

在开头写清支持的起始版本和目标版本,以及运行时、数据库或部署环境的新要求。涉及跨多个主要版本时,交代需要依次完成的升级路径。

把必须处理的破坏性变更排在可选改进前。用读者能辨认的条件说明影响范围,例如“使用自定义缓存路径的项目需要更新配置”。

给出可执行的迁移过程

按实际执行顺序写出准备工作、依赖升级、配置调整、数据变更和验证命令。涉及数据变更时,说明如何备份和确认迁移结果。只有在版本和数据兼容性已经验证的情况下,才记录具体的回退步骤。

配置项改名时,列出旧名称、新名称和类型或默认值的变化。具有代表性的代码可以成对展示,并标明各自适用的版本。完成后提供验证信号,例如新配置已被读取、旧用法的告警消失或关键操作通过。

让整份指南可按影响查找

涉及多项变更时,先给一个列表,说明读者在哪些条件下需要处理每项。每个条目使用实际的选项名或行为,配上从目录可直接点击的标题。单项内容可以按破坏性变更格式写受影响范围、前后差异和验证步骤。

将仍兼容旧版的情况记录在弃用说明中。用迁移示例核对从读者查到配置,到最终明确产物和回退条件的完整路径。