API 穩定性與版本類型
API 穩定性
Koin 專案致力於在版本之間保持高度的相容性。Kotzilla 團隊與所有活躍的維護者努力確保在新版本中引入的任何變更、增強或優化都不會破壞現有的應用程式。 我們深知穩定且可預測的升級路徑對使用者至關重要，因此在演進 API 時，我們努力將中斷降至最低。
實驗性 API - @KoinExperimentalAPI
為了在收集寶貴社群回饋的同時促進創新，我們在 @KoinExperimentalAPI 註解下引入了新功能和 API。此標記表示：
- 開發中：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)，並輔以額外的前綴識別符，用以說明每個版本的成熟度與預期用途。我們使用的前綴包括：
- 候選版本 (Release Candidate, RC)：這些版本是穩定版本的全功能候選版。它們會經過最終測試與精煉。雖然 RC 版本的目標是高度相容，但在正式發佈前，仍可能根據最終回饋進行微調。
- Alpha / Beta：Alpha 與 Beta 版本主要提供測試與回饋之用。它們通常包含實驗性功能，且可能未完全符合穩定 API 的保證。我們鼓勵開發人員在非生產環境中嘗試這些版本，以協助識別潛在問題並引導未來的改進。