kotlin-tooling-immutable-collections-0-5-x-migration
Migrate Kotlin (and Java) code from kotlinx.collections.immutable 0.3.x / 0.4.x to the latest 0.5.x. The 0.5.x line renames every copy-returning method on PersistentList / PersistentMap / PersistentSet / PersistentCollection to a participial form per KEEP-0459 (add→adding, removeAt→removingAt, set→replacingAt, put→putting, clear→cleared, …) and deprecates the old names (WARNING, with ReplaceWith). Driven by the compiler: bump the version, recompile, and apply the rename each deprecation warning names. Use when the user mentions kotlinx.collections.immutable 0.5.x, PersistentList migration, "Use adding() instead", KEEP-0459, or sees deprecation warnings from kotlinx.collections.immutable.
JetBrains · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-immutable-collections-0-5-x-migration技能说明
name: kotlin-tooling-immutable-collections-0-5-x-migration description: > Migrate Kotlin (and Java) code from kotlinx.collections.immutable 0.3.x / 0.4.x to the latest 0.5.x. The 0.5.x line renames every copy-returning method on PersistentList / PersistentMap / PersistentSet / PersistentCollection to a participial form per KEEP-0459 (add→adding, removeAt→removingAt, set→replacingAt, put→putting, clear→cleared, …) and deprecates the old names (WARNING, with ReplaceWith). Driven by the compiler: bump the version, recompile, and apply the rename each deprecation warning names. Use when the user mentions kotlinx.collections.immutable 0.5.x, PersistentList migration, "Use adding() instead", KEEP-0459, or sees deprecation warnings from kotlinx.collections.immutable. license: Apache-2.0 metadata: author: JetBrains version: "2.4.0"
kotlinx.collections.immutable 0.5.x Migration
The 0.5.x line renames every copy-returning method on the persistent collections to a
participial form (per [KEEP-0459]) and deprecates the old names at WARNING level with a
ReplaceWith hint. Migrating is a mechanical, binary-compatible, semantics-preserving
call-site rename — same parameters, order, and return type; only the name changes.
Drive it from the compiler: bump the version, recompile, and fix each deprecation warning —
the warning names the replacement. Source of truth: [0.5.0-MIGRATION.md].
When it applies
Check the version the project currently uses:
- 0.3.x or 0.4.x (any pre-0.5.0) → run the migration below.
- On 0.5.x but not the latest → set the version to the latest 0.5.x and stop. All 0.5.x releases share the same renames, so a within-line bump adds no new deprecations and needs no recompile.
- On the latest 0.5.x, or on 0.6.x and later → nothing to do.
Migration
1. Find the build command
Check README.md, CLAUDE.md, or AGENTS.md for how the project builds; if it isn't
written down, infer it from the build files — Gradle (./gradlew), Maven (mvn, or the
./mvnw wrapper), Bazel
(a bazel wrapper), or a custom script. Record the compile command (and the test command).
In a multi-module project you only need the modules that use the library, plus any you
change — not a whole-repo build.
2. Baseline compile
Compile on the current version and confirm it's green. If it doesn't build now, you can't tell post-migration errors from pre-existing ones — get a working compile command first.
3. Bump to the latest 0.5.x
Find where the version is pinned — grep -rn kotlinx-collections-immutable across the build
files finds it (version catalog, build script, gradle.properties, pom.xml, …) — and set
it to the latest 0.5.x on [Maven Central] (a -beta is fine). If the build pins artifact
hashes (e.g. gradle/verification-metadata.xml), update those too — the cheapest fix is to
copy the new artifact's checksum straight from the dependency-verification failure message
and add just that one entry, rather than regenerating the whole metadata file. The bump is
binary-compatible; old code keeps compiling with warnings. (If the dependency fails to
resolve with a Kotlin metadata-version error, the project's Kotlin is too old for the 0.5.x
artifact — bump Kotlin first.)
4. Recompile and fix the warnings
Recompile. Each renamed method carries @Deprecated(WARNING, ReplaceWith(...)), so the
compiler emits one warning per call site naming the replacement (e.g. "Use removingAll()
instead"). Apply that rename. Repeat compile → fix until no kotlinx.collections.immutable
deprecation warnings remain. (For multiplatform, one target compile surfaces the shared call
sites. Pre-existing factory deprecations such as immutableListOf → persistentListOf
appear the same way — apply those too.) A recompile that fails right after the bump is
failing on these deprecations (plus, if hashes are pinned, a one-time dependency-verification
error) — keep applying the renames the warnings name; don't re-run dependency-resolution or
metadata-regeneration commands to try to clear it.
Trust the compiler — never find/replace by name. The same method names exist on
MutableList / MutableMap / MutableSet and on the .Builder types, which mutate in
place and are not deprecated. Only the sites the compiler flags (receiver statically
Persistent*) get renamed; if it didn't flag it, leave it.
An Unresolved reference after a rename means the participial name isn't on that
receiver — you've split a rename. A rename only compiles if the declaration and every
call site move together. The library already did that for the kotlinx types, so renaming
their call sites just works — but it doesn't hold for anything else that merely shares the
names. When a renamed call won't resolve, there are two cases:
- The receiver is unrelated to this library (a
Mutable*, a.Builder, a same-named method on some other type) — the rename was wrong; revert that site. - The receiver is a project type the codebase is itself migrating — it implements a
Persistent*, or it's the project's own wrapper whose methods echo these names and get renamed to match. The rename is right but half-done: rename the declaration and its other callers too, so the call resolves. (Deprecated overrides on an implementer are step 5.)
Decide by the receiver's declared type, never the method name — a Persistent*-named
field may hold another type. This matters most when you can't lean on a fast recompile and
are renaming from reading the source.
Java callers. The recompile flags them only if the build reports javac deprecation
warnings (-Xlint:deprecation, usually off). If it doesn't, grep the .java files that
import the library for the old names and rename the calls whose receiver is a Persistent*
type.
After the renames, the compiler may report some @Suppress("DEPRECATION") as having no
effect — remove those (re-read the region first, in case