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 の非推奨警告がなくなるまで繰り返します。（マルチプラットフォームでは、いずれか1つのターゲットをコンパイルすれば、共有されている呼び出し箇所が検出されます。immutableListOf → persistentListOf など、以前からあるファクトリーメソッドの非推奨警告も同じように表示されるため、それらも適用してください。）バージョンを上げた直後に再コンパイルが失敗する場合、失敗の原因はこれらの非推奨警告（ハッシュが固定されている場合は、一度だけ発生する依存関係検証エラーも）です。警告に示された名前への変更を続けて適用してください。解消しようとして、依存関係の解決やメタデータの再生成を行うコマンドを再実行しないでください。

コンパイラーを信頼し、名前で検索・置換しないでください。 同じメソッド名は MutableList ／ MutableMap ／ MutableSet や .Builder 型にも存在し、これらはその場で変更を行い、非推奨ではありません。コンパイラーが警告を出した箇所（レシーバーの静的型が Persistent*）だけを変更し、警告が出なかった箇所はそのままにしてください。

変更後に Unresolved reference が発生する場合、そのレシーバーには動名詞形の名前がありません。つまり、名前変更が分断されています。 名前の変更をコンパイルするには、宣言とすべての呼び出し箇所をまとめて移行する必要があります。ライブラリの kotlinx 型ではすでに対応済みなので、呼び出し箇所の名前を変えるだけで動作します。しかし、名前が同じだけの別のものには当てはまりません。変更後の呼び出しが解決されない場合、次の2つのケースがあります。

• レシーバーはこのライブラリとは無関係です（Mutable*、.Builder、または別の型にある同名メソッド）。その箇所の変更は誤りなので、元に戻してください。
• レシーバーは、コードベース自身が移行中のプロジェクト型です。Persistent* を実装しているか、メソッド名がこれらと同じで、合わせて名前が変更されるプロジェクト独自のラッパーです。変更は正しいものの、未完了です。呼び出しを解決できるよう、宣言とその他の呼び出し箇所も名前を変更してください。（実装側の非推奨オーバーライドについては手順5で対応します。）

メソッド名ではなく、レシーバーの宣言された型を基準に判断してください。Persistent* という名前のフィールドでも、別の型を保持している場合があります。コンパイルをすぐに実行できず、ソースを読んで名前を変更する場合には特に重要です。

Java の呼び出し元。 ビルドで javac の非推奨警告（通常は無効になっている -Xlint:deprecation）が報告された場合に限り、再コンパイルで検出されます。報告されない場合は、ライブラリをインポートしている .java ファイルを grep で検索し、レシーバーが 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)

動名詞形のメソッド同士が呼び出し合う場合は、非推奨の名前ではなく、対応する動名詞形のメソッドを経由してください。オーバーライドの本体自体が非推奨メンバーを呼び出す場合に限り、抑制に "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 — 命名の根拠