API 안정성 및 릴리스 유형

API 안정성

Koin 프로젝트는 버전 간 높은 수준의 호환성을 유지하기 위해 최선을 다하고 있습니다. Kotzilla 팀과 모든 활성 메인테이너는 새로운 릴리스에서 도입된 변경 사항, 향상된 기능 또는 최적화가 기존 애플리케이션을 중단시키지 않도록 노력하고 있습니다. 우리는 안정적이고 예측 가능한 업그레이드 경로가 사용자에게 매우 중요하다는 점을 이해하고 있으며, API를 발전시킬 때 중단을 최소화하기 위해 노력하고 있습니다.

실험적 API - @KoinExperimentalAPI

귀중한 커뮤니티 피드백을 수집하면서 혁신을 촉진하기 위해, @KoinExperimentalAPI 어노테이션 아래에 새로운 기능과 API를 도입합니다. 이 지정은 다음을 나타냅니다:

• 활발한 개발 중: API가 아직 설계 단계에 있으며 변경될 수 있습니다.
• 피드백 권장: 개발자가 이러한 기능을 테스트하고 경험을 공유하여, 설계를 다듬고 개선하는 데 도움을 주시기를 바랍니다.
• 잠재적인 파괴적 변경(Breaking changes): 이러한 API는 실험적이기 때문에, 커뮤니티의 의견을 바탕으로 반복하는 과정에서 후속 릴리스에서 수정되거나 제거될 수 있습니다.

지원 중단 정책 - @Deprecated

API의 일부가 단계적으로 폐지될 때 원활한 전환을 보장하기 위해, Koin은 @Deprecated 어노테이션을 사용하여 이러한 영역을 명확하게 표시합니다. 당사의 지원 중단 전략은 다음을 포함합니다:

명확한 경고: 지원 중단된 API에는 권장되는 대안이나 지원 중단 이유를 나타내는 메시지가 함께 제공됩니다.

지원 중단 수준:

• Warning: API를 여전히 사용할 수는 있지만, 사용을 권장하지 않으며 가능한 한 빨리 교체해야 함을 나타냅니다.
• Error: 해당 API가 더 이상 사용되지 않으며 컴파일되지 않음을 의미하여, 중요한 변경 사항이 즉시 처리되도록 보장합니다.

이러한 접근 방식은 개발자가 오래된 API에 의존하는 코드를 식별하고 업데이트하는 데 도움을 주어, 기술 부채를 줄이고 더 깨끗하고 견고한 코드베이스를 위한 길을 열어줍니다. 업데이트의 복잡성에 따라 API와 함께 ReplaceWith가 제공될 수 있습니다.

내부 API - @KoinInternalAPI

Koin 프레임워크 내에서 내부적으로만 사용하도록 의도된 기능의 경우, @KoinInternalAPI 어노테이션을 도입합니다. 이 API들은 공개 계약(Public contract)의 일부가 아니며 다음을 따릅니다:

• 내부 사용 전용: Koin의 내부 메커니즘만을 위해 설계되었습니다.
• 변경될 수 있음: 사전 고지 없이 향후 릴리스에서 수정되거나 제거될 수 있습니다.
• 외부 사용 지양: 장기적인 호환성을 유지하기 위해 개발자는 애플리케이션 코드에서 이러한 API를 사용하지 않는 것이 좋습니다.

Kotlin의 @OptIn 어노테이션을 사용한 명시적 동의

Koin에서 실험적 API 및 지원 중단된 API를 사용하는 경우 명시적 동의(Opt-in)가 필요하며, 이를 통해 개발자가 API의 상태와 잠재적 위험을 충분히 인지하도록 합니다. Kotlin의 @OptIn 어노테이션을 사용함으로써, 사용자는 자신의 코드가 실험적이거나 지원 중단으로 표시된 API에 의존하고 있음을 명시적으로 인정하게 됩니다.

릴리스 유형

Koin은 각 릴리스의 성숙도와 의도된 용도를 나타내는 추가 접두사 식별자와 함께 유의적 버전(SemVer)을 준수합니다. 우리가 사용하는 접두사는 다음과 같습니다:

• 릴리스 후보 (Release Candidate, RC): 이 릴리스는 안정 버전을 위한 기능이 완료된 후보입니다. 최종 테스트와 개선을 거칩니다. RC 버전은 높은 호환성을 목표로 하지만, 공식 릴리스 전 최종 피드백에 따라 사소한 변경이 여전히 발생할 수 있습니다.
• 알파 (Alpha) / 베타 (Beta): 알파 및 베타 버전은 주로 테스트와 피드백을 위해 제공됩니다. 종종 실험적인 기능을 포함하며 안정적인 API 보장을 완전히 준수하지 않을 수 있습니다. 개발자는 잠재적인 문제를 식별하고 향후 개선 사항을 안내하는 데 도움이 되도록 비프로덕션 환경에서 이러한 릴리스를 사용해 볼 것을 권장합니다.