SuperAPI AI 工具集

version-migration-guide

通用与其它

查看项目

更新于 10-16 08:45

技能介绍

用途:为从版本 N 升级到 N+1 的项目编写或审计迁移指南。指南属于 Diátaxis 中的 how-to,只说明读者需要做什么、按什么顺序做,不承担教学职责。

主要能力:先做范围检查,确认任务不是变更日志、版本策略或教程;依据 Churn Rule 与 Hyrum's Law 判断是否该写指南(能自行迁移的内部消费者应做 codemod 而非写指南)。通过访谈确定版本对、迁移面与受众,冻结范围,从 API diff、变更日志、弃用警告、示例应用提交与支持工单中盘点破坏项,并按影响范围排序。

使用方式:先写运行时、语言、依赖等最低要求;每条破坏性变更按六部分撰写——带稳定锚点的动词标题、affected-if 检测信号、三句以内的变更原因、// Before 与 // After 代码、修复步骤或 codemod 命令、逃生开关(无则明说)。随后给出弃用时间线表格、自动化工具及其边界、清理项与按错误文本索引的排障章节,并通过冷启动升级验证。

适用场景:库/SDK 迁移为默认形态;schema、云、移动、浏览器等迁移需参考 guide-types-beyond-libraries.md;跨网络边界时参考 api-version-migration.md。受众分为开源自助、商业合同与内部强制三类,写法各有侧重。

限制:不负责变更日志、版本方案决策、消费者侧实际升级或日常错误文档;路径形态(分阶段、单跳、兼容构建、顺序桥接)需按项目条件选择;兼容构建需有发布后维护者,否则不应列入方案。资料未提供具体命令、价格或平台信息。