종속 항목 버전 업그레이드

종속 항목을 업그레이드하면 최신 기능, 버그 수정, 개선사항을 이용할 수 있습니다. 종속 항목을 업그레이드하려면 Gradle에서 요청한 버전을 확인하는 방법, 관련 위험, 이러한 위험을 완화하기 위해 취할 수 있는 조치를 이해해야 합니다.

업그레이드 전략 고려

업그레이드의 가장 중요한 단계는 위험 분석입니다. 업그레이드할 각 종속 항목에 얼마나 만족하는지 확인합니다. 업그레이드 전략을 정의할 때 고려해야 할 사항은 다음과 같습니다.

라이브러리 빌드

사용자가 기기에 다운로드하여 실행하는 애플리케이션을 빌드하고 있나요? 아니면 다른 개발자가 애플리케이션을 빌드하는 것을 지원하기 위해 라이브러리를 빌드하고 있나요?

애플리케이션을 빌드하는 경우 애플리케이션을 최신 상태로 안정적으로 유지하는 데 중점을 두어야 합니다.

라이브러리를 빌드하는 경우 다른 개발자의 애플리케이션에 중점을 두어야 합니다. 업그레이드는 소비자에게 영향을 미칩니다. 종속 항목 중 하나를 업그레이드하면 해당 버전이 Gradle의 종속 항목 확인 후보가 되며, 이로 인해 애플리케이션에서 해당 종속 항목을 사용할 수 없게 될 수 있습니다.

첫째, 가능하면 라이브러리의 종속 항목을 최소화합니다. 종속 항목이 적을수록 소비자의 종속 항목 확인에 미치는 영향이 줄어듭니다.

시맨틱 버전 관리를 따라 변경사항 유형을 표시해야 합니다. 예를 들어 AndroidX는 시맨틱 버전 관리를 따르고 출시 전 버전 관리 체계를 추가합니다. 소비자가 중단되지 않도록 major 버전 업그레이드를 피하세요.

사용자가 조기에 테스트할 수 있도록 라이브러리의 출시 후보 (RC)를 만드는 것이 좋습니다.

라이브러리의 애플리케이션 바이너리 인터페이스 (ABI) 호환성을 유지하는 방법에 관한 자세한 내용은 라이브러리 작성자를 위한 하위 호환성 가이드라인을 참고하세요. 통합 테스트와 바이너리 호환성 검사기와 같은 도구를 사용하여 ABI 변경사항이 의도한 버전 변경사항과 일치하는지 확인합니다.

patch에서 라이브러리의 하위 버전으로 수정사항을 출시하는 경우 소비자는 새 기능을 원하지 않는 한 라이브러리를 다음 major 또는 minor 버전으로 업그레이드할 필요가 없습니다. 이러한 업그레이드에서는 전이 종속 항목을 업그레이드하지 마세요.

라이브러리 업그레이드에 소비자에게 특히 불편을 줄 수 있는 중대한 변경사항이 필요한 경우 이전 버전과 새 버전이 공존하고 더 점진적인 출시가 가능하도록 새 아티팩트로 출시하는 것이 좋습니다.

참고: 종속 항목 중 하나의 업그레이드에 주요 API 변경사항이 포함된 경우 major 또는 minor 출시에서 업그레이드하고 필요한 변경사항을 적용하는 것이 좋습니다. 그러지 않으면 라이브러리 사용자가 종속 항목을 업데이트하여 라이브러리와 종속 항목 간에 비호환성이 발생할 수 있습니다. 라이브러리가 변경되지 않은 경우에도 이 문제가 발생할 수 있습니다. 종속 항목을 업그레이드하기 위해 새 버전을 출시할 수 있습니다.

출시 주기

애플리케이션 또는 라이브러리는 얼마나 자주 출시하나요?

개발 및 출시 주기 단축

  • 업그레이드할 시간이 얼마 남지 않았습니다.
  • 빠르게 뒤처질 수 있습니다.
  • 소규모 업그레이드를 자주 하면 워크로드를 줄일 수 있습니다.
  • 라이브러리 업그레이드에 문제가 발생하면 해당 업그레이드를 더 빠르게 롤백할 수 있습니다.
  • Dependabot 및 Renovate와 같은 도구를 사용하면 워크로드가 줄어들지만 결과를 분석하여 위험을 확인해야 합니다.

더 긴 개발 및 출시 주기

  • 업그레이드를 진행하고 테스트할 시간이 더 많습니다.
  • 주기 중에 종속 항목의 최신 버전이 출시될 가능성이 높습니다.
  • 업그레이드를 롤백하고 애플리케이션 또는 라이브러리를 출시하는 데 시간이 더 오래 걸립니다.

최신 기능을 확인해 보세요

사용 가능한 최신 기능과 API를 사용하고 싶나요? 아니면 기능이나 버그 수정이 필요할 때만 업그레이드하고 싶나요?

빈번한 업그레이드의 장단점을 고려하세요. 향후 업그레이드가 더 쉬워지지만 (통합할 변경사항이 적음) 업그레이드 위험이 더 자주 발생합니다.

라이브러리의 출시 전 버전 (알파, 베타, 출시 후보)으로 업그레이드하는 테스트를 진행하면 안정화 버전을 사용할 수 있을 때 준비하는 데 도움이 됩니다.

새 종속 항목

새 종속 항목을 추가하는 경우 라이브러리의 모든 위험 기준을 검토하여 적절하게 평가되었는지 확인하는 강력한 검토 절차를 고려하세요. 검토 없이 새 종속 항목을 추가할 수 없습니다.

전담팀

전담 빌드팀이 있나요? 소프트웨어 엔지니어가 빌드를 유지하나요? 전담팀은 엔지니어가 새 버전을 사용하기 전에 빌드가 제대로 작동하는지 확인하기 위해 업그레이드 위험을 분석하고 새 버전을 테스트하는 데 더 많은 시간을 할애할 수 있습니다.

업그레이드 유형

일부 업그레이드는 다른 업그레이드보다 중요합니다. 가장 중요한 항목을 생각해 보세요.

Gradle 및 Gradle 플러그인과 같은 빌드 도구 업그레이드는 일반적으로 사용자에게 미치는 영향이 적으며 대부분의 위험은 빌드 내부에서 발생합니다. 빌드 자체가 이러한 변경사항을 검증하는 데 도움이 됩니다. 라이브러리 및 SDK 업그레이드는 검증하기가 더 어렵고 사용자에게 더 큰 위험을 초래합니다.

Android Gradle 플러그인 (AGP): Android 애플리케이션 또는 라이브러리를 빌드하는 데 사용되는 도구입니다. 성능 개선, 버그 수정, 새로운 린트 규칙, 새로운 Android 플랫폼 버전 지원이 포함되거나 사용 설정되는 경우가 많으므로 이 업그레이드는 가장 중요한 업그레이드입니다.

Gradle: AGP 또는 다른 Gradle 플러그인을 업그레이드할 때는 종종 Gradle을 업그레이드해야 합니다.

기타 Gradle 플러그인: Gradle의 플러그인 API가 변경되는 경우가 있습니다. Gradle을 업그레이드할 때는 사용하는 플러그인의 업그레이드가 있는지 확인합니다.

Kotlin 및 Java: 일부 라이브러리와 플러그인에는 최소 버전의 Kotlin 또는 Java가 필요하거나 새로운 언어 기능, API 또는 성능 개선사항을 활용하려는 경우

Android 플랫폼: Play 스토어에는 정기적인 Android SDK 업그레이드가 필요합니다. 최대한 빨리 새 버전의 Android SDK를 테스트해야 합니다. 일부 SDK 업그레이드에는 새로운 권한 또는 새 API 사용과 같은 애플리케이션 변경이 필요합니다.

라이브러리: 전체 아키텍처와의 근접성을 기준으로 라이브러리의 우선순위를 지정하고 싶나요?

  • AndroidX와 같은 플랫폼 및 아키텍처 관련 라이브러리는 새로운 기능을 활용하거나 플랫폼의 추상화 변경을 돕기 위해 자주 변경됩니다. Android 플랫폼 또는 기타 아키텍처 관련 라이브러리를 업그레이드할 때마다 이러한 라이브러리를 업그레이드하세요.
  • 새 기능이나 특정 버그 수정이 필요하지 않은 한 다른 라이브러리 업그레이드는 분산되거나 지연될 수 있습니다.

Android 스튜디오: Android 스튜디오를 최신 상태로 유지하면 최신 Android SDK를 사용할 수 있도록 기본 IntelliJ IDEA 플랫폼 및 도구의 최신 기능과 버그 수정사항을 이용할 수 있습니다.

사용 가능한 도구

업그레이드를 지원하는 여러 도구와 플러그인이 있습니다. Dependabot 및 Renovate와 같은 도구는 빌드에서 라이브러리 버전을 자동으로 업그레이드하지만 결과를 분석하여 위험을 확인해야 합니다.

특정 유형의 업그레이드 전략

일부 유형의 종속 항목을 업그레이드하면 다른 유형의 종속 항목을 업그레이드해야 하는 연쇄 효과가 발생할 수 있습니다. 빌드 요소 간의 관계는 도구 및 라이브러리 상호의존성에서 설명합니다.

빌드 종속 항목 및 종속 항목 간의 관계
그림 1. 관계를 구축합니다.

각 유형의 구성요소를 업그레이드할 때는 업그레이드가 빌드의 다른 구성요소에 미치는 영향을 고려하세요.

Android Gradle 플러그인 (AGP)

Android 스튜디오에는 이러한 작업을 지원할 수 있는 AGP 업그레이드 어시스턴트가 포함되어 있습니다.

어시스턴트를 사용하거나 업그레이드를 수동으로 실행하는 경우 다음 사항을 고려하세요.

AGP 출시 노트를 참고하세요.

나열된 버전 이상으로 Gradle을 업그레이드합니다.

선택한 AGP 버전을 지원하는 버전으로 Android 스튜디오를 업그레이드합니다.

사용하려는 Android SDK를 지원하는 Android 스튜디오 및 AGP 버전을 사용합니다.

SDK Build Tools, NDK, JDK와의 호환성을 확인합니다.

AGP의 데이터를 확장하거나 사용하는 Gradle 플러그인 (내부 또는 공개용)을 개발하는 경우 플러그인을 업그레이드해야 하는지 확인하세요. AGP에서 API를 지원 중단하고 나중에 삭제하여 이전 플러그인과의 비호환성이 발생하는 경우가 있습니다.

Kotlin 컴파일러, 언어, 런타임

Kotlin 출시 노트에서 알려진 문제와 비호환성을 확인하세요.

Jetpack Compose를 사용하는 경우:

Kotlin Symbol Processing (KSP)을 사용하는 경우 설정은 KSP 빠른 시작을, 사용 가능한 버전은 KSP 출시를 참고하세요. Kotlin 버전과 일치하는 KSP 버전을 사용해야 합니다. 예를 들어 Kotlin 2.0.21을 사용하는 경우 2.0.21로 시작하는 모든 버전의 KSP 플러그인(예: 2.0.21-1.0.25)을 사용할 수 있습니다. 일반적으로 KSP 프로세서 (예: 빌드 파일에서 ksp 종속 항목으로 표시되는 Room 컴파일러)를 업그레이드할 필요가 없습니다. KSP 플러그인은 대부분의 컴파일러 API를 추상화하며 프로세서에서 사용하는 KSP API는 안정적입니다.

사용 중인 다른 모든 Kotlin 컴파일러 플러그인을 업그레이드합니다. Kotlin 컴파일러 플러그인 API는 출시마다 자주 변경되며 플러그인은 호환되는 API를 사용해야 합니다. 플러그인이 컴파일러 플러그인에 나열된 경우 Kotlin 컴파일러와 동일한 버전을 사용해야 합니다. 다른 컴파일 플러그인의 경우 문서에서 적절한 매핑을 확인하세요.

Kotlin 컴파일러 자체와 함께 유지보수되지 않는 컴파일러 플러그인은 컴파일러 플러그인 API가 안정화될 때까지 기다리면서 출시가 지연되는 경우가 많습니다. Kotlin을 업그레이드하기 전에 사용하는 모든 컴파일러 플러그인에 일치하는 업그레이드가 있는지 확인합니다.

마지막으로 Kotlin 언어가 변경되어 코드를 업데이트해야 하는 경우도 있습니다. 이는 실험용 기능을 사용해 볼 때 가장 자주 발생합니다. Kotlin 컴파일러를 업그레이드한 후 코드가 제대로 빌드되지 않으면 Kotlin 출시 노트에서 언어 변경사항 또는 런타임 라이브러리 손상이 있는지 확인하세요.

Kotlin 컴파일러 플러그인

Kotlin 컴파일러 플러그인을 업그레이드해야 하는 경우 사용 중인 Kotlin 버전과 일치하는 버전으로 업그레이드합니다.

대부분의 Kotlin 컴파일러 플러그인은 Kotlin 컴파일러와 동일한 버전을 사용하거나 필요한 버전의 Kotlin 컴파일러로 시작합니다. 예를 들어 플러그인 버전이 2.0.21-1.0.25인 경우 Kotlin 컴파일러 버전 2.0.21을 사용해야 합니다.

Kotlin 컴파일러 버전을 변경하려면 기타 변경사항이 필요한 경우도 있습니다.

라이브러리

라이브러리는 빌드에서 가장 흔히 업그레이드되는 종속 항목입니다. Android 스튜디오 편집기에서 사용 가능한 업그레이드가 표시되거나 일부 종속 항목 도구 및 플러그인을 사용하는 경우 업그레이드가 표시됩니다.

일부 라이브러리는 라이브러리를 사용하는 데 필요한 최소 compileSdk 또는 minSdk를 지정합니다. 지정된 compileSdk를 하나 이상 사용하지 않으면 빌드가 실패합니다. 그러나 애플리케이션의 minSdk는 라이브러리 종속 항목 및 빌드 파일에 지정된 모든 minSdk 값의 최대값으로 자동 설정됩니다.

일부 라이브러리는 사용해야 하는 최소 Kotlin 버전도 지정합니다. 빌드 파일의 Kotlin 버전을 지정된 버전 이상으로 업데이트합니다.

Gradle

새 버전의 Gradle에서 기존 API를 지원 중단하여 향후 출시에서 해당 API를 삭제하는 경우가 있습니다. Gradle 플러그인을 개발하는 경우 특히 플러그인이 공개된 경우 최대한 빨리 플러그인을 업그레이드하세요.

일부 Gradle 업그레이드에서는 사용하는 플러그인의 새 버전을 찾아야 합니다. 이러한 플러그인은 최신 Gradle 플러그인 API와 일치하도록 플러그인을 업그레이드할 때 개발이 지연될 수 있습니다.

Gradle을 업그레이드하려면 다음 단계를 따르세요.

  • 사용하려는 버전의 출시 노트를 읽습니다.
  • gradle/wrapper/gradle-wrapper.properties에서 Gradle 버전을 업그레이드합니다.
  • ./gradlew wrapper --gradle-version latest를 실행하여 Gradle 래퍼 jar 및 스크립트를 업그레이드합니다.
  • Gradle 플러그인을 업그레이드합니다.
  • Gradle을 실행하는 데 사용되는 JDK를 업그레이드합니다.

Gradle 플러그인

업그레이드된 Gradle 플러그인은 새 또는 변경된 Gradle API를 사용하는 경우가 있으며, 이 경우 Gradle을 업그레이드하거나 빌드 파일의 구성을 변경해야 할 수 있습니다. 두 경우 모두 비호환성을 나타내는 빌드 경고 또는 오류가 표시됩니다.

플러그인을 업그레이드할 때마다 Gradle도 업그레이드합니다.

Android SDK

Android 스튜디오에는 이러한 작업에 도움이 되는 Android SDK 업그레이드 어시스턴트가 포함되어 있습니다.

어시스턴트를 사용하거나 업그레이드를 수동으로 실행하는 경우 다음 사항을 고려하세요.

Android SDK의 각 출시에는 새로운 기능과 API, 버그 수정, 동작 변경사항이 포함되어 있습니다. Play 스토어에서 targetSdk를 업데이트해야 합니다. 하지만 필요한 사항을 변경할 시간을 더 확보할 수 있도록 기한보다 일찍 targetSdk를 업데이트하는 것이 좋습니다.

Android SDK를 업그레이드하기 전에 출시 노트를 주의 깊게 읽어보세요. 다음과 같은 동작 변경 섹션에 주의하세요.

  • 설치 또는 런타임 시 요청해야 하는 새로운 권한입니다.
  • 지원 중단된 API 및 대체 API
  • API 또는 동작의 브레이킹 체인지
  • 코드에 영향을 줄 수 있는 새로운 Kotlin 또는 Java API

동작 변경사항 섹션은 상당히 길 수 있지만 애플리케이션에 적용해야 하는 중요한 변경사항이 포함되는 경우가 많으므로 주의 깊게 살펴보세요.

Play 스토어 요구사항을 충족하려면 targetSdk를 업그레이드해야 합니다. compileSdk 업그레이드는 선택사항이며, 업그레이드하면 새 API에 액세스할 수 있습니다. AndroidX와 같은 일부 라이브러리에는 최소 compileSdk 요구사항이 포함되어 있습니다.

개발 중에 새로운 SDK 기능을 활용하고 빌드 중에 호환성을 보장하려면 Android Gradle 플러그인 (AGP)과 Android 스튜디오를 업그레이드하세요. 여기에는 새로운 SDK를 위한 새롭고 개선된 도구가 포함됩니다. Android API 수준 도구 최소 버전을 참고하세요.

Android SDK를 업그레이드할 때 사용하는 AndroidX 라이브러리를 업그레이드합니다. AndroidX는 Android SDK 버전 전반에서 더 나은 호환성과 성능을 위해 새롭고 업데이트된 API를 사용하는 경우가 많습니다.

Android 스튜디오

일반적으로 언제든지 Android 스튜디오를 업그레이드할 수 있습니다. AGP를 업그레이드하거나 Android SDK를 업그레이드하라는 메시지가 표시될 수 있습니다. 이러한 업그레이드는 적극 권장되지만 필수는 아닙니다.

나중에 Android 스튜디오를 사용하여 AGP 또는 Android SDK를 업그레이드하려면 도구 메뉴에서 다음 옵션을 찾으세요.

자바

Android 애플리케이션에 Java 소스 코드가 있는 경우 최신 Java API를 활용하는 것이 좋습니다.

각 Android SDK 버전은 Java API의 하위 집합과 언어 기능을 지원합니다. AGP는 디슈가링이라는 프로세스를 사용하여 이전 Android SDK 버전과의 호환성을 제공합니다.

Android SDK 출시 노트에는 지원되는 Java 수준과 잠재적인 문제가 지정되어 있습니다. Kotlin은 동일한 Java API에 액세스할 수 있으므로 이러한 문제 중 일부는 Kotlin 소스 코드에도 영향을 줄 수 있습니다. Java 소스 코드가 없더라도 출시 노트의 동작 변경사항 섹션에 표시되는 JDK API 섹션에 세심한 주의를 기울여야 합니다.

JDK 사용은 빌드 스크립트의 여러 위치에 지정됩니다. 자세한 내용은 Android 빌드의 Java 버전을 참고하세요.

업그레이드 분석

종속 항목을 업그레이드하면 API 및 동작 변경사항, 새로운 사용 요구사항, 새로운 보안 문제 또는 라이선스 변경사항의 형태로 위험이 발생할 수 있습니다. 예를 들어 다음과 같은 작업을 해야 하나요?

  • API 변경사항에 맞게 코드 변경
  • 새 권한 검사를 추가하시겠습니까?
  • 동작 변경사항에 맞게 테스트를 추가하거나 기존 테스트를 수정해야 하나요?

업그레이드한 종속 항목이 자신의 종속 항목 버전을 업그레이드했다고 가정해 보겠습니다. 이렇게 하면 대규모 변경사항을 빠르게 스파이더링할 수 있습니다.

Renovate 또는 Dependabot과 같은 도구를 사용하여 업그레이드를 자동화하는 경우 이러한 도구는 분석을 수행하지 않으며 최신 라이브러리 버전으로 업그레이드합니다. 이러한 유형의 자동 업그레이드 후 모든 것이 제대로 작동한다고 가정하지 마세요.

성공적인 업그레이드의 핵심은 업그레이드 분석입니다.

  1. 업그레이드 전과 후의 종속 항목 차이를 확인합니다.
  2. 각 변경사항을 검토하고 관련 위험을 파악합니다.
  3. 위험을 완화하거나 변경사항을 수락하거나 거부합니다.

종속 항목 차이점 확인

업그레이드 분석의 첫 번째 단계는 종속 항목이 어떻게 변경되는지 확인하는 것입니다. 버전 제어 (VCS, 예: Git) 및 Dependency Guard 플러그인을 활용하여 변경사항을 빠르게 확인합니다. 전과 후 스냅샷을 만들어 비교하는 것이 목표입니다.

첫 번째 기준을 설정하고 만들기

업그레이드를 시작하기 전에 프로젝트가 성공적으로 빌드되는지 확인합니다.

최대한 많은 경고를 해결하거나 기준을 만들어 이미 확인한 경고를 추적하는 것이 좋습니다.

이러한 경고 기준을 사용하면 종속 항목을 업그레이드할 때 도입된 새로운 경고를 더 쉽게 확인할 수 있습니다.

종속 항목 가드를 설정하고 실행하여 종속 항목 기준을 만듭니다. gradle/libs.versions.toml 버전 카탈로그에 다음을 추가합니다.

[versions]
dependencyGuard = "0.5.0"

[plugins]
dependency-guard = { id = "com.dropbox.dependency-guard", version.ref = "dependencyGuard" }

앱의 빌드 파일에 다음을 추가합니다.

Kotlin

plugins {
    alias(libs.plugins.dependency.guard)
}

dependencyGuard {
    configuration("releaseRuntimeClasspath")
}

Groovy

plugins {
    alias(libs.plugins.dependency.guard)
}

dependencyGuard {
    configuration('releaseRuntimeClasspath')
}

releaseRuntimeClasspath 구성이 가능성이 높은 타겟이지만 다른 구성을 사용하려면 빌드 파일에 나열된 구성 없이 ./gradlew dependencyGuard를 실행하여 사용 가능한 모든 구성을 확인하세요.

설정이 완료되면 ./gradlew dependencyGuard를 실행하여 app/dependencies/releaseRuntimeClasspath.txt에서 보고서를 생성합니다. 이는 기준 보고서입니다. 버전 제어 시스템 (VCS)에 커밋하여 저장합니다.

Dependency Guard는 라이브러리 종속 항목 목록만 캡처합니다. 빌드 파일에는 Android SDK 및 JDK 버전과 같은 다른 종속 항목도 있습니다. 종속 항목이 변경되기 전에 VCS에 커밋하면 VCS의 차이에서도 이러한 변경사항이 강조 표시됩니다.

업그레이드 및 기준과 비교

기준이 있으면 테스트하려는 종속 항목과 기타 빌드 변경사항을 업그레이드합니다. 이 시점에서는 소스 코드나 리소스를 업그레이드하지 마세요.

./gradlew lint를 실행하여 새 린트 경고 또는 오류를 확인합니다. 중요한 문제를 해결한 후 ./gradlew lint -Dlint.baselines.continue=true를 실행하여 경고 기준을 업데이트합니다. Kotlin 경고 기준 또는 Kotlin 경고 기준 생성기와 같이 다른 도구를 사용하여 경고 기준을 캡처한 경우 새 경고를 해결하고 기준도 업데이트합니다.

./gradlew dependencyGuard를 실행하여 기준 보고서를 업데이트합니다. 그런 다음 VCS diff를 실행하여 라이브러리가 아닌 변경사항을 확인합니다. 생각보다 훨씬 많은 라이브러리 업그레이드가 포함될 수 있습니다.

위험 분석

변경사항을 파악한 후 업그레이드된 각 라이브러리의 잠재적 위험을 고려합니다. 이렇게 하면 테스트에 집중하거나 변경사항을 더 깊이 조사하는 데 도움이 됩니다. 일관된 분석을 위해 프로젝트에서 분석할 위험을 정의합니다.

몇 가지 고려사항:

메이저 버전 버그 수정

주 버전 번호가 변경되었나요?

시맨틱 버전 관리에서 첫 번째 숫자를 주 버전이라고 합니다. 예를 들어 라이브러리 버전이 1.2.3에서 2.0.1로 업그레이드된 경우 주요 버전이 변경된 것입니다. 이는 일반적으로 라이브러리 개발자가 버전 간에 호환되지 않는 변경사항(예: API의 일부 삭제 또는 변경)을 적용했음을 나타냅니다.

이 경우 다음 고려사항을 살펴볼 때 영향을 받는 라이브러리에 특히 주의하세요.

코드에서 주석이나 빌드 파일 사양을 사용하도록 선택해야 하는 실험용 API를 사용하는 경우 1.2.3에서 1.3.1로 업그레이드하거나 1.2.3에서 1.2.5로 업그레이드하는 등 마이너 버전 또는 패치 버전 변경사항이 추가 위험을 초래할 수 있습니다.

비안정 API

일부 라이브러리 출시에는 안정적이지 않은 API가 포함될 수 있습니다. 이러한 API는 일반적으로 진행 중인 작업이거나 다른 불안정한 API에 종속된 API입니다.

일반적으로 알파, 개발자, 실험용 출시와 같은 미리보기로 제한되지만 일부 라이브러리에는 실험용 또는 불안정으로 표시된 API가 포함되어 있습니다.

가능하면 이러한 API를 사용하지 마세요. 이러한 API를 사용해야 하는 경우 사용 기록을 기록하고 이후 출시에서 변경사항 또는 삭제 여부를 확인하세요.

동적 동작

일부 라이브러리는 외부 요인에 따라 다르게 동작합니다. 예를 들어 서버와 통신하는 라이브러리는 해당 서버의 변경사항에 종속됩니다.

  • 라이브러리가 특정 서버 버전과 일치해야 하나요?
  • 라이브러리를 여러 버전의 서버에 연결할 수 있나요?
  • 다른 외부 요인이 라이브러리의 올바른 동작에 영향을 미치나요?

매니페스트 병합

Android 보관 파일 (AAR)로 게시된 라이브러리에는 애플리케이션에 병합된 리소스와 매니페스트가 포함될 수 있습니다. 이를 통해 간접적으로 실행되는 새로운 권한과 Android 구성요소(예: 활동 또는 broadcast receiver)를 추가할 수 있습니다.

런타임 업데이트

일부 라이브러리는 애플리케이션의 제어 외부에서 업데이트할 수 있는 기능을 사용합니다. 라이브러리는 Android SDK와 별개로 업그레이드되는 Play 서비스를 사용할 수 있습니다. 다른 라이브러리는 독립적으로 업데이트된 외부 애플리케이션의 서비스에 바인딩될 수 있습니다 (AIDL을 사용하는 경우가 많음).

건너뛸 버전은 몇 개인가요?

라이브러리 업그레이드를 늦출수록 잠재적인 위험이 커집니다. 버전이 크게 변경되는 경우(예: 1.2.3에서 1.34.5로) 이 라이브러리에 특히 주의하세요.

이전 가이드

라이브러리에 이전 가이드가 있는지 확인합니다. 이를 통해 위험 분석 및 완화 계획을 크게 줄일 수 있습니다.

이러한 가이드가 있으면 개발자가 호환성에 중점을 두고 업그레이드 완화를 고려했음을 나타냅니다.

출시 노트

변경된 각 라이브러리의 출시 노트 (제공된 경우)를 참고하세요. 추가된 권한과 같은 중대한 변경사항 또는 새로운 요구사항의 징후를 찾습니다.

리드미

라이브러리의 일부 리드미 파일에는 특히 라이브러리가 출시 노트를 제공하지 않는 경우 잠재적인 위험이 명시되어 있습니다. _알려진 문제_, 특히 알려진 보안 문제를 찾습니다.

알려진 취약점 확인

Play SDK 색인은 많은 인기 SDK의 취약점을 추적합니다. Play Console은 알려진 취약점이 있는 나열된 SDK 중 하나를 사용하고 있는지 보고합니다. Android 스튜디오에서 빌드 파일을 수정할 때 IDE는 SDK 색인을 확인하고 취약한 라이브러리 버전 사용을 신고합니다.

미국 국립 표준 기술 연구소 (NIST)는 대규모 국가 취약점 데이터베이스 (NVD)를 유지 관리합니다. Dependency Check Gradle 플러그인은 사용된 종속 항목을 NVD와 비교하여 확인합니다.

Dependency Check를 사용하려면 NVD API 키를 요청하고, Gradle 플러그인을 설정하고, ./gradlew dependencyCheckAnalyze를 실행합니다. 실행하는 데 시간이 오래 걸릴 수 있습니다.

버전 충돌

버전이 예상대로 확인되나요? 충돌, 특히 주요 버전 차이를 찾습니다. 충돌을 찾는 방법에 관한 자세한 내용은 Gradle 종속 항목 확인을 참고하세요. 특히 ./gradlew app:dependencies 보고서에서 ->를 검색합니다.

가능하면 종속 항목의 작성자와 협력하여 종속 항목의 충돌을 해결합니다. 회사에서 허용하는 경우 라이브러리의 호환성을 개선하는 데 도움이 되도록 라이브러리에 변경사항을 기여 (업스트림)합니다.

라이선스 확인

라이브러리를 업그레이드할 때 라이선스 변경사항을 확인합니다. 라이브러리 자체가 더 이상 애플리케이션 또는 라이브러리와 호환되지 않는 라이선스로 변경될 수 있습니다. 새로운 전이 종속 항목으로 인해 호환되지 않는 라이선스가 도입될 수도 있습니다. 종속 항목에서 현재 라이선스 집합을 확인하는 방법에 관한 자세한 내용은 라이선스 유효성 검사를 참고하세요.

유지보수 및
품질 위험

공개 저장소가 있는 라이브러리의 경우:

  • 라이브러리를 유지관리하는 참여자는 몇 명인가요?
  • 마지막 업그레이드 시기는 언제이며 라이브러리는 얼마나 자주 변경되나요?
  • 문제 백로그 (제공되는 경우)는 어떻게 표시되나요? 훑어보면서 라이브러리의 잠재적 문제와 기술적 부채를 파악합니다.
  • 단위 테스트가 라이브러리를 얼마나 잘 다루나요?
  • 코드베이스에 알려진 반패턴이 있나요?
  • 라이브러리가 잘 문서화되어 있나요?
  • 코드베이스에 _fixme_ 주석이 많나요?

오픈소스와 비공개 소스 비교

라이브러리가 오픈소스인 경우 코드 또는 라이브러리 코드에 문제가 있든 관계없이 비공개 소스보다 문제를 디버그하기가 더 쉽습니다.

비공개 소스 종속 항목을 최소화하고 평가 중에 추가로 면밀히 검토합니다. 사용 사례에 적합한 대안이 있나요? 폐쇄 소스 라이브러리에 어떤 서비스수준계약을 사용할 수 있나요? 폐쇄 소스 종속 항목을 사용하기로 선택한 경우 위험을 제한하는 데 도움이 되는 추가 테스트 사례를 작성할 준비를 하세요.

빌드 실행

프로젝트를 빌드합니다. 새로운 오류 또는 경고를 찾습니다. 문제를 일으키는 라이브러리를 식별할 수 있는 경우 해당 라이브러리를 업그레이드할 때 발생할 수 있는 위험으로 간주합니다.

새로운 지원 중단 경고가 표시되면 이를 생성하는 라이브러리의 구체적인 위험으로 추가합니다. 이러한 메서드는 이후 버전에서 삭제될 수 있습니다. 해당 라이브러리를 계속 사용하려면 지원 중단된 API 사용에서 대체 API로 전환하는 데 시간을 할애하거나 지원 중단을 기록하여 이러한 함수와 나중에 삭제되는지 여부를 주시하세요.

린트를 사용하여 API 문제를 감지

Android 린트는 종속 항목 또는 Android SDK 버전 변경으로 인한 문제 등 애플리케이션의 여러 문제를 포착할 수 있습니다. 예를 들어 compileSdk를 업그레이드하고 새 API를 사용하는 경우 이전 SDK 버전에서 사용할 수 없는 API가 린트에서 보고됩니다.

린트는 Android 스튜디오 편집기에서 실행되며 변경사항이 있을 때마다 문제를 보고합니다. 하지만 build 또는 lint 타겟을 사용하지 않는 한 일반적으로 스튜디오의 빌드의 일부로 실행되거나 명령줄 빌드를 실행할 때 실행되지 않습니다.

지속적 통합 (CI)을 사용하는 경우 CI 빌드 중에 (또는 적어도 야간 빌드에서) gradlew build 또는 gradlew lint를 실행하여 이러한 유형의 오류를 포착합니다.

CI를 사용하지 않는 경우에도 가끔 gradlew lint를 실행해야 합니다.

린트 오류 및 경고에 특히 주의하세요. 일부 라이브러리는 자체 린트 검사와 함께 제공되므로 API를 올바르게 사용할 수 있습니다. 일부 새 라이브러리 버전에는 새로운 린트 경고 및 오류가 포함되어 빌드 시 새로운 보고서가 생성됩니다.

위험 완화

업그레이드 위험을 파악한 후 위험을 완화할 방법을 결정합니다.

  • 일부 위험은 있는 그대로 수용합니다. 특히 업그레이드 시간과 리소스가 제한된 경우 허용 가능한 수준으로 낮은 위험이 있습니다.
  • 일부 위험은 즉시 거부합니다. 특히 지금 위험을 완화할 시간이나 리소스가 부족한 경우 일부 업그레이드는 너무 위험할 수 있습니다. 분류해야 하는 경우 발생한 버그 또는 필요한 새 기능에 필요한 업그레이드에 집중하세요.
  • 남은 위험 완화
    • 업그레이드를 더 작고 독립적인 변경사항 세트로 일괄 처리하는 것이 좋습니다. 이렇게 하면 전반적인 위험이 줄어들고 부분적인 롤백이 가능합니다.
    • 변경사항을 자세히 조사합니다.
    • 앱을 테스트하여 예기치 않은 변경사항이 있는지 확인합니다. 업그레이드에 대한 신뢰를 구축하는 데 필요한 경우 새 테스트를 추가합니다.
    • 의심스러운 점이 발견되면 출처 (제공되는 경우)를 살펴봅니다.
    • 소스 또는 빌드에서 필요한 사항을 변경합니다.

결정사항을 문서화합니다. 업그레이드로 인한 위험이 애플리케이션 실행 시 문제가 되는 경우 위험 분석 문서를 작성하면 필요한 오류 분석을 줄일 수 있습니다.

라이선스 유효성 검사

라이브러리 개발자가 라이브러리에 대한 라이선스를 부여합니다. 라이선스 약관을 준수해야 라이브러리를 사용할 수 있습니다. 일부 라이선스는 매우 관대하여 라이브러리 저작자 표시와 최종 사용자에게 라이선스 텍스트를 표시하는 것만 요구하는 경우가 많습니다. 일부 라이브러리는 바이럴로 간주됩니다. 이러한 라이브러리를 사용하는 경우 애플리케이션 또는 라이브러리에 동일한 라이선스를 적용해야 합니다.

라이선스는 출시마다 변경될 수 있습니다. 업그레이드할 때마다 사용 중인 종속 항목에 애플리케이션 또는 라이브러리와 호환되는 라이선스가 부여되어 있는지 확인해야 합니다.

라이선스가 호환되지 않거나 더 이상 호환되지 않도록 변경된 경우 해당 버전의 라이브러리를 사용할 수 없습니다. 방법은 다음과 같습니다.

  • 라이브러리 소유자에게 연락하여 기존 라이선스 또는 이중 라이선스를 계속 사용하도록 요청하여 이전 라이선스를 계속 허용합니다.
  • 법무팀과 협력하여 호환되도록 라이선스를 변경할 수 있는지 확인하세요.
  • 호환되는 라이선스가 있는 다른 라이브러리를 찾아 필요에 따라 애플리케이션을 수정합니다.
  • 호환되는 마지막 라이브러리 버전을 포크하고 (라이선스가 파생 저작물을 허용하고 변경사항이 소급되지 않는 경우) 직접 수정합니다.