API の安定性とリリースタイプ

API の安定性

Koin プロジェクトは、バージョン間の高いレベルの互換性を維持することに尽力しています。Kotzilla チームおよびすべてのアクティブなメンテナーは、新しいリリースで導入された変更、機能強化、または最適化が既存のアプリケーションを壊さないように努めています。安定した予測可能なアップグレードパスがユーザーにとって重要であることを理解しており、API を進化させる際に中断を最小限に抑えるよう努めています。

試験的な API - @KoinExperimentalAPI

貴重なコミュニティのフィードバックを集めながらイノベーションを促進するために、@KoinExperimentalAPI アノテーションの下で新しい機能と API を導入します。この指定は以下を示します。

活発な開発中: API はまだ設計段階にあり、変更される可能性があります。
フィードバックを推奨: 開発者の皆様には、これらの機能をテストし、経験を共有して、設計を改良および改善にご協力をお願いします。
潜在的な破壊的変更: これらの API は試験的なものであるため、コミュニティからの意見に基づいて反復する際に、その後のリリースで変更または削除される可能性があります。

非推奨ポリシー - @Deprecated

API の一部が段階的に廃止される際の円滑な移行を確実にするために、Koin は @Deprecated アノテーションを使用して、これらの領域を明確にマークします。当社の非推奨戦略には以下が含まれます。

明確な警告: 非推奨の API には、推奨される代替手段または非推奨の理由を示すメッセージが付属しています。

非推奨レベル:

Warning (警告): API はまだ利用可能ですが、その使用は推奨されず、できるだけ早く置き換える必要があることを示します。
Error (エラー): API はもはや使用を意図しておらず、コンパイルされないことを示し、重要な変更が迅速に対処されるようにします。

このアプローチは、開発者が古い API に依存するコードを特定して更新し、技術的負債を削減し、よりクリーンで堅牢なコードベースへの道を開くのに役立ちます。更新の複雑さに応じて、ReplaceWith を API とともに提供できます。

内部 API - @KoinInternalAPI

Koin フレームワーク内での内部使用のみを目的とした機能のために、@KoinInternalAPI アノテーションを導入します。これらの API はパブリックコントラクトの一部ではなく、以下のような特徴があります。

内部使用のみ: Koin の内部メカニズム専用に設計されています。
変更される可能性: 事前通知なしに、将来のリリースで変更または削除される可能性があります。
外部での使用は避けてください: 長期的な互換性を維持するために、開発者はアプリケーションコードでこれらの API を使用しないようにしてください。

Kotlin の @OptIn アノテーションによるオプトイン

Koin での試験的および非推奨の API の使用には、オプトインが必要です。これにより、開発者は API のステータスと潜在的なリスクを十分に認識できます。 Kotlin の @OptIn アノテーションを使用することにより、コードが試験的であるか、非推奨としてマークされている API に依存していることを明示的に認めます。

リリースの種類

Koin は、各リリースの成熟度と意図された用途を示す追加のプレフィックス識別子を持つセマンティックバージョニング (SemVer) に準拠しています。使用するプレフィックスは次のとおりです。

Release Candidate (RC): これらのリリースは、安定バージョンの機能が完了した候補です。最終テストと改良が行われます。RC バージョンは高度な互換性を持つように意図されていますが、公式リリース前の最終フィードバックに基づいて、小さな変更が発生する可能性があります。
Alpha / Beta: アルファ版およびベータ版は、主にテストとフィードバックのために利用できます。これらには、試験的な機能が含まれていることが多く、安定した API 保証に完全には準拠していない可能性があります。開発者は、潜在的な問題を特定し、将来の改善を導くために、非本番環境でこれらのリリースを試すことをお勧めします。