kotlin-tooling-immutable-collections-0-5-x-migration — Claude Code

---
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 it still covers something else).

### 5. Custom implementers

If the project has classes that implement `PersistentList` / `PersistentMap` /
`PersistentSet` / `PersistentCollection`, their deprecated overrides need migrating too.
Find them:

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

On Windows PowerShell, `Select-String` is the `grep` equivalent:

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

(Confirm a match really lists the interface as a *supertype*, not just a field type or type
argument.) For each, move the implementation into the new participial method and have the
deprecated override delegate to it:

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

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

If the participial methods call each other, route those calls through participial siblings,
not the deprecated names. (Add `"DEPRECATION"` to the suppress only when an override body
itself still calls a deprecated member.) Doing this now matters: at 0.6.0 the old names
become compile errors, and at 0.7.0 they are removed. See [`0.5.0-MIGRATION.md`] for the
upstream implementer guidance.

### 6. Run any documented follow-up steps

Do this *after* the renames compile clean, so that if you run low on time the call-site work
is already done. Some projects document steps to run after a dependency change that the
compiler won't surface — most commonly regenerating dependency-verification metadata (the
`gradle/verification-metadata.xml` hashes from step 3). Usually the single-entry fix from
step 3 is all you need; only fall back to the project's documented full-regeneration procedure
(in `README.md` / `CONTRIBUTING.md` / `CLAUDE.md` / `AGENTS.md`) if that one entry isn't
enough. Run it **once** — a full `--write-verification-metadata` / "resolve all dependencies"
pass re-resolves the entire graph and is slow, and repeating it rarely changes the outcome.
Then re-confirm the build is clean.

## Rename reference

- **`PersistentCollection`** — `add`→`adding`, `addAll`→`addingAll`, `remove`→`removing`, `removeAll`→`removingAll`, `retainAll`→`retainingAll`, `clear`→`cleared`
- **`PersistentList`** (the above, plus) — `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`

Builders (`PersistentList.Builder`, etc.) are **not** renamed — they mutate in place, so
their imperative names stay.

## Links

- [`0.5.0-MIGRATION.md`] — upstream guide (source of truth, incl. implementer details)
- [KEEP-0459] — naming rationale

[KEEP-0459]: https://github.com/Kotlin/KEEP/blob/main/proposals/KEEP-0459-naming-conventions-for-copy-returning-operations.md
[`0.5.0-MIGRATION.md`]: https://github.com/Kotlin/kotlinx.collections.immutable/blob/master/docs/0.5.0-MIGRATION.md
[Maven Central]: https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-collections-immutable/versions