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