APIの安定性とリリースタイプ
このページでは、Koin APIの安定性に関する規約について説明します。具体的には、新しいAPIがどのように導入され、古いAPIがどのように削除されるか、また各リリースタイプが何を保証しているかについて解説します。各バージョンの変更点については、Releases & Upgrade Guides を参照してください。
バージョン間の互換性
Koinは、バージョンをまたいでも既存のアプリケーションが動作し続けることを目指しています。Kotzillaチームおよびメンテナーは、新しいリリースにおける変更、改善、最適化によって既存のコードが破壊されないよう確認を行っています。APIを変更しなければならない場合でも、アップグレードの計画が立てられるよう、以下の実験的フェーズおよび非推奨フェーズの手順を踏んで行われます。
実験的API (Experimental APIs)
新機能は、まず @KoinExperimentalAPI アノテーションを付与して公開されます。実験的APIには以下のような特徴があります。
- アクティブに開発中: 設計は最終決定されたものではなく、変更される可能性があります。
- フィードバック受付中: 実際に試して、うまくいく点や改善が必要な点をフィードバックしてください。それが最終的な設計に反映されます。
- 保証なし: フィードバックに基づいて、今後のリリースで変更または削除される可能性があります。
オプトイン(Opt-in)せずに実験的APIを使用すると、コンパイラ警告が発生します。Kotlinの @OptIn を使用してオプトインしてください。
@OptIn(KoinExperimentalAPI::class)
fun setupKoin() { ... }オプトインを行うことで、不安定なAPIへの依存がコード内で明示的になります。
注意が必要なAPI (Delicate APIs)
@KoinDelicateAPI は、取り扱いに注意が必要な安定版APIを示します。これらは特殊で高度なユースケースを対象としており、誤った使い方をすると実行時に予期しない動作を引き起こす可能性があります。実験的APIと同様に、@OptIn(KoinDelicateAPI::class) でオプトインするまではコンパイラ警告が発生します。オプトインする前に、APIドキュメントを必ず確認してください。
非推奨API (Deprecated APIs)
段階的に廃止されるAPIには、Kotlinの @Deprecated が付与されます。メッセージには、代替手段または非推奨となった理由が記載されています。簡単な変更である場合は、ReplaceWith によってIDEから自動的に適用できます。
非推奨化は2つのレベルを経て行われます。
- Warning(警告): APIは引き続き動作しますが、早期に置き換える必要があります。
- Error(エラー): APIはコンパイルできなくなります。アップグレードする前に置き換える必要があります。
Errorレベルで非推奨となったAPIは、通常その後のリリースで削除されます。各バージョンの非推奨事項や削除されたAPIについては、リリースノートに記載されています。
内部API (Internal APIs)
@KoinInternalApi は、Koin自身の内部メカニズムのために存在する関数やクラスに付与されます。これらは公開API規約の一部ではありません。
- 内部利用専用: アプリケーションコードのためではなく、Koinの実装のために用意されています。
- 変更される可能性あり: 事前の予告なく、任意のリリースで変更または削除される可能性があります。
オプトインせずに使用した場合はコンパイルエラーになります。アプリケーションコードからオプトインして使用しないでください。
リリースタイプ
Koinはセマンティックバージョニング(Major.Minor.Patch、詳細は Versions, Roadmap & Support を参照)に従います。プレリリースバージョンには、その成熟度を示すサフィックスが付与されます。
- AlphaおよびBeta: テストおよびフィードバックの収集を目的として公開されます。多くの場合、実験的な機能が含まれており、安定したAPIの保証には完全には従いません。本番環境以外の環境で使用してください。
- Release Candidate (RC): 安定バージョンの候補として機能的に完全(feature-complete)であり、最終テスト段階にあるものです。最終リリースとの互換性が見込まれていますが、フィードバックに応じて小規模な変更が行われる可能性があります。
関連情報
- Releases & Upgrade Guides: 各バージョンの変更点、非推奨事項、削除項目。
- Versions, Roadmap & Support: リリースサイクルとサポートオプション。
- Migrating from KSP to the Compiler Plugin: 非推奨となったKSPプロセッサからの移行。
