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

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:

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:

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:

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