Android projesinde Gradle, AGP ve bağımlılıkları güvenle güncelleme

Kısaca: Güncellemeleri şu sırayla yapın — Gradle Wrapper → Android Gradle Plugin → Kotlin/eklentiler → kütüphaneler; her adımdan sonra derlemeyi çalıştırın ve hataları not edin. Aşağıda kompakt bir adım adım plan, komutlar ve tipik hataları gidermek için hazır çözümler yer alıyor.

Başlamadan önce — hazırlık ve genel sıra

• Git'te bir dal/etiket oluşturun ve mevcut durumu commit edin (git tag/branch).
• Güncelleme sırası: 1) Gradle Wrapper, 2) AGP (classpath veya version catalog), 3) Kotlin ve eklentiler, 4) bağımlılıklar. Adımlar arasında ./gradlew clean assembleDebug çalıştırın ve hataları düzeltin.

Yararlı komutlar:

./gradlew wrapper --gradle-version 8.13 --distribution-type all
./gradlew --version
./gradlew clean assembleDebug --stacktrace --info

Adım adım güncelleme algoritması

1. Wrapper'ı güncelleyin:
   • Wrapper komutunu çalıştırın veya gradle/wrapper/gradle-wrapper.properties dosyasını düzenleyin.
   • gradlew, gradlew.bat ve gradle/wrapper/ içeriğini commit edin.
2. AGP'yi güncelleyin:
   • Kök build.gradle dosyasında (veya settings.gradle.kts/version catalog sürümlerinde) gerekli com.android.tools.build:gradle değerini ayarlayın.
   • Projeyi senkronize edin, derleyin ve hataları not edin.
3. Kotlin/eklentileri güncelleyin:
   • AGP ile uyumlu bir Kotlin sürümü seçin.
   • AGP 9+ için org.jetbrains.kotlin.android eklentisinin gerekip gerekmediğini kontrol edin.
4. Kütüphaneleri güncelleyin:
   • Merkezi yönetim için sürümleri Version Catalog'a (gradle/libs.versions.toml) taşıyın.
   • Denetim için ben‑manes eklentisini kullanın:

plugins { id "com.github.ben-manes.versions" version "0.47.0" }
./gradlew dependencyUpdates

Tipik derleme hataları ve hazır çözümler

• "Minimum supported Gradle version is X": wrapper'ı güncelleyin ve ./gradlew'u depodan çalıştırın (CI wrapper kullanmalıdır).
• "Could not find com.android.tools.build:gradle": google() ve mavenCentral() depolarını ekleyin, çevrimdışı modun kapalı olduğundan emin olun.
• namespace/compileSdk hataları: modüle şunu ekleyin

android {
  namespace "com.example.app"
  compileSdk 34
}

• Duplicate class: bağımlılık ağacına bakın (./gradlew :app:dependencies --configuration debugRuntimeClasspath), geçişli bağımlılıkları hariç tutun:

implementation('com.some:lib:1.2.3') { exclude group: 'com.conflict', module: 'conflicting-module' }

• KAPT/annotation processor: işlemci sürümlerini güncelleyin, correctErrorTypes etkinleştirin veya KSP'ye geçiş yapın.
• Dex limiti / multidex: multiDexEnabled etkinleştirin ve androidx.multidex ekleyin veya bağımlılıkları azaltın.

Destek araçları ve uygulamalar

• Version Catalogs (libs.versions.toml) — merkezi sürüm yönetimi.
• Ben‑manes/versions — eski artefaktların düzenli kontrolü.
• Uyumlu kütüphane aileleri için BOM.
• Geçişli sürümleri eşitlemek için Dependency constraints/force.

Sık yapılan hatalar

• CI, wrapper yerine sistem gradle kullanıyor — CI betiklerini düzeltin.
• JDK uyumsuzluğu (yeni Gradle/AGP için CI'da JDK 17+ gerekir).
• CI/yerel ortamda eski önbellekler — önbelleği temizleyerek ve ./gradlew --stop ile çözülür.

SSS

• AGP için hangi Gradle sürümünün gerektiğini hızlıca nasıl anlarım?
  AGP sürüm notlarını kontrol edin: burada desteklenen minimum Gradle sürümü ve gereken JDK belirtilir.
• Tüm bağımlılıkların güncellenmesini otomatikleştirebilir miyim?
  Evet, ancak manuel kontrol olmadan önerilmez: otomatik güncellemeler sıkça API'yi bozar.
• Güncellemeden sonra annotation processor'lar hata verirse ne yapmalıyım?
  İşlemci sürümlerini güncelleyin, kapt.correctErrorTypes = true etkinleştirin veya KSP'ye geçiş yapın.

Güncelleme sonrası yayın öncesi kontrol listesi:

• debug/release derlemeleri tamamlandı, testler geçti, CI temiz makinede derlendi, ortam talimatları güncellendi, wrapper/versions.toml commit edildi.

İsterseniz build.gradle(ler) ve gradle-wrapper.properties dosyalarını gönderin — projeniz için adım adım bir güncelleme planı ve örnek bir libs.versions.toml hazırlayayım.