# 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...

- Repository: https://github.com/Kotlin/kotlin-agent-skills (1104 stars)
- Category: Mobile
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-immutable-collections-0-5-x-migration -g -a claude-code -y`
Codex: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-immutable-collections-0-5-x-migration -g -a codex -y`
Cursor: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-immutable-collections-0-5-x-migration -g -a cursor -y`
Gemini CLI: `npx skills add Kotlin/kotlin-agent-skills --skill kotlin-tooling-immutable-collections-0-5-x-migration -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Kotlin/kotlin-agent-skills`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/Kotlin/kotlin-agent-skills/blob/HEAD/skills/kotlin-tooling-immutable-collections-0-5-x-migration/SKILL.md