kotlin-tooling-immutable-collections-0-5-x-migration

kotlinx.collections.immutable 0.5.x 迁移

0.5.x 系列将持久化集合中所有返回副本的方法重命名为现在分词形式（参见 KEEP-0459），并以 WARNING 级别弃用旧名称，同时提供 ReplaceWith 提示。迁移只需在调用处机械地重命名，保持二进制兼容且不改变语义——参数、顺序和返回类型均相同，只有名称变更。

以编译器为准进行迁移：升级版本、重新编译，并修复每条弃用警告——警告会指出替代名称。权威来源：0.5.0-MIGRATION.md。

适用情况

检查项目当前使用的版本：

• 0.3.x 或 0.4.x（任何低于 0.5.0 的版本）→ 执行以下迁移。
• 使用 0.5.x，但不是最新版本 → 将版本设为最新的 0.5.x，然后停止。所有 0.5.x 版本使用相同的重命名，因此在同一系列中升级不会引入新的弃用项，也无需重新编译。
• 使用最新的 0.5.x，或 0.6.x 及更高版本 → 无需处理。

迁移

1. 查找构建命令

查看 README.md、CLAUDE.md 或 AGENTS.md，了解项目如何构建；如果没有写明，则根据构建文件推断——Gradle（./gradlew）、Maven（mvn 或 ./mvnw 包装器）、Bazel（bazel 包装器）或自定义脚本。记录编译命令（以及测试命令）。对于多模块项目，只需构建使用该库的模块，以及你要修改的模块，无需构建整个代码仓库。

2. 基线编译

使用当前版本进行编译并确认构建通过。如果现在无法构建，就无法区分迁移后出现的错误和已有错误——应先找到可用的编译命令。

3. 升级到最新的 0.5.x

找到固定版本的位置——在构建文件中运行 grep -rn kotlinx-collections-immutable 即可查找（版本目录、构建脚本、gradle.properties、pom.xml 等）——并将其设为 Maven Central 上最新的 0.5.x（使用 -beta 版本也可以）。如果构建固定了制品哈希（例如 gradle/verification-metadata.xml），也要更新这些哈希——最省事的做法是直接从依赖验证失败消息中复制新制品的校验和，只添加这一条，而不是重新生成整个元数据文件。此升级保持二进制兼容；旧代码仍可编译，但会出现警告。（如果依赖因 Kotlin 元数据版本错误而无法解析，说明项目使用的 Kotlin 版本过旧，无法支持 0.5.x 制品——请先升级 Kotlin。）

4. 重新编译并修复警告

重新编译。每个重命名的方法都带有 @Deprecated(WARNING, ReplaceWith(...))，因此编译器会针对每个调用位置发出一条警告，并指出替代名称（例如 “改用 removingAll()”）。按提示重命名。重复执行编译 → 修复，直到不再有 kotlinx.collections.immutable 弃用警告。（对于多平台项目，编译一个目标即可显示共享调用位置。immutableListOf → persistentListOf 等预先存在的工厂方法弃用也会以同样方式显示——也要按提示处理。）升级后立即编译失败，原因是这些弃用警告（此外，如果固定了哈希值，还可能出现一次性的依赖验证错误）——继续按警告提示重命名；不要重新运行依赖解析或元数据重新生成命令来试图消除错误。

相信编译器——绝不要按名称查找并替换。 MutableList / MutableMap / MutableSet 和 .Builder 类型也存在同名方法，它们会原地修改，且未弃用。只有编译器标记的调用位置（接收者的静态类型为 Persistent*）才要重命名；如果编译器没有标记，就保持原样。

重命名后出现 Unresolved reference，意味着该接收者上没有对应的分词形式名称——你只改了一部分。 只有声明和所有调用位置一并迁移，重命名才能通过编译。该库已经为 kotlinx 类型完成了这一迁移，因此只重命名它们的调用位置即可；但对其他仅仅共享这些名称的类型来说，并非如此。如果重命名后的调用无法解析，有两种情况：

• 接收者与此库无关（Mutable*、.Builder，或其他类型上的同名方法）——重命名有误；撤销该位置的修改。
• 接收者是代码库正在迁移的项目类型——它实现了 Persistent*，或是项目自有的包装类型，其方法名称与这些名称相同，因此也要随之重命名。重命名方向正确，但尚未完成：同时重命名声明及其其他调用者，让调用可以解析。（实现类上的弃用重写见第 5 步。）

应根据接收者的声明类型判断，绝不要只看方法名称——一个名称中带有 Persistent* 的字段，其实际类型可能是其他类型。如果不能快速重新编译，而是通过阅读源码进行重命名，这一点尤其重要。

Java 调用者。 只有在构建报告 javac 弃用警告时（通常需要启用 -Xlint:deprecation）重新编译才会标记它们。如果没有标记，请在导入该库的 .java 文件中搜索旧名称，并重命名接收者类型为 Persistent* 的调用。

重命名后，编译器可能会报告某些 @Suppress("DEPRECATION") 已不起作用——请移除它们（先重新查看相关代码段，以防它仍涵盖其他内容）。

5. 自定义实现类

如果项目中有实现了 PersistentList / PersistentMap / PersistentSet / PersistentCollection 的类，也需要迁移它们已弃用的重写。查找这些类：

grep -rnE --include='*.kt' \
  '(class|object|interface)\s+\w[^:]*:\s*[^{]*\b(PersistentList|PersistentMap|PersistentSet|PersistentCollection)\s*<' .

在 Windows PowerShell 中，Select-String 是 grep 的等效命令：

Get-ChildItem -Recurse -Filter *.kt |
  Select-String '(class|object|interface)\s+\w[^:]*:\s*[^{]*\b(PersistentList|PersistentMap|PersistentSet|PersistentCollection)\s*<'

（请确认匹配结果中该接口确实列为超类型，而不只是字段类型或类型参数。）对于每个匹配项，将实现移到新的分词形式方法中，并让已弃用的重写委托给它：

override fun adding(element: E): MyList<E> = /* real implementation */

@Suppress("OVERRIDE_DEPRECATION")
override fun add(element: E): MyList<E> = adding(element)

如果分词形式的方法会互相调用，请通过分词形式的同级方法转发这些调用，不要使用已弃用的名称。（只有在重写方法体本身仍调用已弃用成员时，才在 suppress 中添加 "DEPRECATION"。）现在就做这一步很重要：到 0.6.0 时，旧名称会变成编译错误；到 0.7.0 时，它们会被移除。有关上游实现类的指导，请参阅 0.5.0-MIGRATION.md。

6. 执行所有有文档记录的后续步骤

请在重命名操作通过编译后再执行此步骤，这样即使时间不够，调用点的修改也已经完成。有些项目会记录依赖项变更后需要执行的步骤，而编译器不会提示这些步骤——最常见的是重新生成依赖项验证元数据（第 3 步中的 gradle/verification-metadata.xml 哈希值）。通常只需按第 3 步修正单个条目；只有在单条目修正不够时，才使用项目文档中记录的完整重新生成流程（见 README.md / CONTRIBUTING.md / CLAUDE.md / AGENTS.md）。只需运行一次——完整的 --write-verification-metadata /“解析所有依赖项”操作会重新解析整个依赖关系图，速度很慢，重复执行也很少能改变结果。然后再次确认构建通过。

重命名参考

• PersistentCollection — add→adding、addAll→addingAll、remove→removing、removeAll→removingAll、retainAll→retainingAll、clear→cleared
• PersistentList（除上述内容外）— add(i, e)→addingAt、addAll(i, c)→addingAllAt、set(i, e)→replacingAt、removeAt→removingAt
• PersistentMap — put→putting、putAll→puttingAll、remove(k)→removing、remove(k, v)→removing、clear→cleared

构建器（例如 PersistentList.Builder）不会重命名——它们会原地修改，因此仍使用命令式名称。

链接

• 0.5.0-MIGRATION.md — 上游指南（权威来源，包含实现者详细信息）
• KEEP-0459 — 命名理由