SuperAPI AI 工具集

writing-migration-guides

编程与开发

查看项目

更新于 10-16 07:12

技能介绍

用途

该技能用于在 supabase-swift 项目中为破坏性变更(breaking change)编写迁移指南。触发场景包括:fix!:/feat!: 提交、BREAKING CHANGE: 页脚,或任何改变公共 API 形态或行为的编辑。

主要能力

  • 判断某个变更是否需要迁移条目:重命名或改变类型的公共符号、改变的默认值、改变的错误类型、触发方式不同的事件等都需要;单纯的弃用不需要,改用 @available(*, deprecated, ...) 消息。
  • 定位或创建迁移文件:supabase-swift 在仓库根目录为每个即将发布的大版本维护一个迁移指南,覆盖所有模块,文件名为 V<N>_MIGRATION.md。<N> 是高于最新发布标签的下一个大版本号,可用 git tag --sort=-v:refname | head -1 查看;若最新标签是 v2.55.0,则 <N> 为 3,文件为 V3_MIGRATION.md。若文件已存在则追加新的 ## 章节,仅当该版本尚无文件时才创建。
  • 撰写章节:以反引号包裹具体符号或行为作为 ## 标题,然后依次写“变更内容”(一两句话,点名具体类型/名称)、“原因”(具体起因,如暴露的 bug、服务器实际发送的形态、与其他 Supabase SDK 的不一致)、“前后代码”(真实可编译的 Swift 调用点,非伪代码)、“是否编译报错”(明确说明是编译错误还是静默行为变更,并告知读者搜索什么)、“逃生通道”(若旧行为仍可达,展示方式)。当变更涉及超过两三个重命名或替换时,使用 | Before | After | 表格。
  • 文件内排序与分组:若文件已有针对同一版本其他变更的章节,新增独立 ## 章节,而非并入现有章节,以保持每个变更可独立链接。
  • 交叉链接与验证:在 PR 描述中链接该指南;若破坏性变更带有弃用回退,用 @available(*, deprecated, message: "Use X instead. See migration guide: https://github.com/supabase-community/supabase-swift/blob/main/V<N>_MIGRATION.md") 指向指南;运行 ./scripts/spell-check.sh,必要时将项目专有术语加入 dictionary.txt。

使用方式

按步骤执行:确认需要条目 → 找到文件(不新建)→ 撰写章节 → 文件内排序与分组 → 交叉链接并验证。每步都有完成标准,例如能说出具体变更的符号或行为、知道确切文件路径及是创建还是追加、章节包含 What/Why/Before-After 并明确是否编译错误、拼写检查通过且指南在 PR 描述中被点名。

适用场景

适用于 supabase-swift 中即将发布大版本的破坏性变更。不适用于一次性功能迁移指南(如 docs/migrations/RealtimeV2 Migration Guide.md),后者记录从旧 API 迁移到新的并行 API,而非版本升级,应保持原样。

限制

该技能针对 supabase-swift 仓库的约定,包括文件命名、目录位置和脚本路径。它不涵盖非破坏性变更的文档,也不处理功能迁移指南。常见错误包括:为每个破坏性变更创建新文件、创建按模块划分的文件、以“为了保持一致”作为全部原因、在前后代码中使用伪代码、未说明是否编译错误、用散文罗列大量重命名、重命名无关的一次性指南以套用版本化模式。