APIの安定性とリリースの種類

APIの安定性

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

実験的API - @KoinExperimentalAPI

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

• 活発に開発中: APIはまだ設計段階にあり、変更される可能性があります。
• フィードバックの推奨: 開発者の皆様にこれらの機能をテストし、体験を共有していただくことで、設計の洗練と改善に役立てるようお願いしています。
• 破壊的変更の可能性: これらのAPIは実験的なものであるため、コミュニティからの入力に基づいた反復作業の中で、その後のリリースで修正または削除される可能性があります。

非推奨ポリシー - @Deprecated

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

明確な警告：非推奨のAPIには、推奨される代替案や非推奨の理由を示すメッセージが添えられています。

非推奨レベル：

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

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

内部API - @KoinInternalAPI

Koinフレームワーク内での内部使用のみを厳密に意図した機能については、 @KoinInternalAPI アノテーションを導入しています。これらのAPIは公開コントラクトの一部ではなく、以下の特徴があります：

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

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

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

リリースの種類

Koinは、各リリースの成熟度と意図された用途を示す追加のプレフィックス識別子を伴うセマンティックバージョニング（SemVer）を遵守しています。使用するプレフィックスは以下の通りです：

• リリース候補 (RC): これらのリリースは、安定版に向けた機能が完成した候補です。最終的なテストと洗練が行われます。RC版は高い互換性を持つことを意図していますが、正式リリース前の最終的なフィードバックに基づいて、マイナーな変更が依然として発生する可能性があります。
• Alpha / Beta: アルファ版およびベータ版は、主にテストとフィードバックのために提供されます。これらには実験的な機能が含まれることが多く、安定したAPIの保証に完全に準拠していない場合があります。潜在的な問題を特定し、将来の改善を導くために、開発者の皆様には非プロダクション環境でこれらのリリースを試すことをお勧めします。