Esegui l'upgrade delle versioni delle dipendenze

L'upgrade delle dipendenze ti permette di accedere alle loro ultime funzionalità, correzioni di bug e miglioramenti. Per eseguire l'upgrade delle dipendenze, devi comprendere come Gradle risolve le versioni richieste, i rischi connessi e i passaggi che puoi svolgere per mitigarli.

Nota: i test delle app efficaci sono fondamentali per garantire che gli upgrade non causino errori nella compilazione o nell'app in modi imprevisti.

Valuta la tua strategia di upgrade

Il passaggio più importante di qualsiasi upgrade è l'analisi dei rischi. Determina il tuo livello di dimestichezza con ogni dipendenza di cui esegui l'upgrade. Esistono molti aspetti da considerare per definire la strategia di upgrade, tra cui:

Crea una libreria	Stai creando un'applicazione che gli utenti scaricano ed eseguono su un dispositivo? Oppure stai creando una libreria per aiutare altri sviluppatori a creare le loro applicazioni? Se stai creando un'applicazione, il tuo obiettivo dovrebbe essere mantenerla aggiornata e stabile. Se stai creando una libreria, devi concentrarti sulle applicazioni di altri sviluppatori. Gli upgrade influiscono sui tuoi consumatori. Se esegui l'upgrade di una delle dipendenze, questa versione diventa una candidata per la risoluzione delle dipendenze di Gradle, con il rischio di interrompere l'utilizzo della dipendenza da parte dell'applicazione. Innanzitutto, riduci al minimo le dipendenze della libreria, se possibile. Meno dipendenze hai, minore sarà l'impatto sulla risoluzione delle dipendenze del tuo consumatore. Assicurati di seguire il versionamento semantico per indicare i tipi di modifiche che stai apportando. Ad esempio, AndroidX segue il versionamento semantico e aggiunge uno schema di versionamento pre-release. Cerca di evitare gli upgrade alla versione major per non causare problemi ai consumatori. Valuta la possibilità di creare una release candidate (RC) della tua libreria da testare in anteprima dagli utenti. Consulta le linee guida sulla compatibilità con le versioni precedenti per gli autori delle librerie per informazioni dettagliate su come mantenere compatibile l'interfaccia a bit dell'applicazione (ABI) della libreria. Utilizza test di integrazione e strumenti come lo strumento di convalida della compatibilità binaria per assicurarti che le modifiche all'ABI corrispondano alla modifica della versione prevista. Se rilasci correzioni in una versione patch a versioni precedenti della libreria, i tuoi consumatori non devono eseguire l'upgrade della libreria alla versione major o minor successiva, a meno che non vogliano nuove funzionalità. Evita di eseguire l'upgrade delle dipendenze transitive in questi upgrade. Se l'upgrade della libreria richiede modifiche che potrebbero essere particolarmente gravose per i tuoi consumatori, valuta la possibilità di rilasciarle come nuovo elemento in modo che la versione precedente e quella nuova possano coesistere e consentire un implementazione più graduale. Nota: se un upgrade a una delle tue dipendenze contiene una modifica importante all'API, probabilmente ti consigliamo di eseguirlo in una release major o minor e apportare le modifiche necessarie. In caso contrario, potrebbero farlo gli utenti della tua raccolta, causando incompatibilità tra la raccolta e la dipendenza. Ciò potrebbe accadere anche se non sono state apportate modifiche alla raccolta. Puoi rilasciare una nuova versione solo per eseguire l'upgrade della dipendenza.
Ciclo di rilascio	Con quale frequenza rilasci la tua applicazione o libreria? Cicli di sviluppo e rilascio più brevi Il tempo per eseguire l'upgrade è ridotto. Puoi rapidamente rimanere indietro. Piccoli upgrade frequenti possono semplificare il carico di lavoro. Se un upgrade della libreria diventa problematico, puoi eseguire il rollback più rapidamente. Strumenti come Dependabot e Renovate riducono il carico di lavoro, ma assicurati di analizzare i risultati per verificare la presenza di rischi. Cicli di sviluppo e rilascio più lunghi Hai più tempo per eseguire e testare gli upgrade. È più probabile che vengano rilasciate versioni più recenti delle dipendenze durante il ciclo. Il rollback degli upgrade e il rilascio dell'applicazione o della libreria richiedono più tempo.
Non perderti le ultime funzionalità	Preferisci utilizzare le API e le funzionalità più recenti disponibili o eseguire l'upgrade solo quando hai bisogno di una funzionalità o di una correzione di bug? Considera i pro e i contro degli upgrade frequenti. Gli upgrade futuri sono più semplici (meno modifiche da integrare), ma ti assumi i rischi legati all'upgrade più spesso. Testare gli upgrade alle versioni di pre-release (alpha, beta, release candidate) delle librerie può contribuire alla preparazione quando sono disponibili release stabili.
Nuova dipendenza	Se aggiungi una nuova dipendenza, valuta la possibilità di sottoporre la libreria a un'attenta procedura di revisione che esamini tutti i criteri di rischio per assicurarti che siano stati valutati correttamente. Non consentire l'aggiunta di nuove dipendenze senza revisione.
Team dedicato	Hai un team di build dedicato? I tuoi tecnici software gestiscono la build? Spesso un team dedicato può dedicare più tempo all'analisi dei rischi relativi agli upgrade e al test di nuove versioni per garantire che la build funzioni correttamente prima che gli ingegneri utilizzino le nuove versioni.
Tipo di upgrade	Alcuni upgrade sono più importanti di altri. Pensa a quali sono i più importanti per te. Gli upgrade degli strumenti di compilazione, come Gradle e i plug-in Gradle, in genere hanno un impatto minore sugli utenti e gran parte del rischio è interno alla compilazione. La build stessa aiuta a convalidare queste modifiche. Gli upgrade delle librerie e degli SDK sono più difficili da convalidare e presentano un rischio maggiore per gli utenti. Android Gradle Plugin (AGP): gli strumenti utilizzati per compilare l'applicazione o la libreria Android. Si tratta dell'upgrade più importante che puoi eseguire, in quanto spesso include o attiva miglioramenti delle prestazioni, correzioni di bug, nuove regole di lint e il supporto per le nuove versioni della piattaforma Android. Gradle: spesso è necessario eseguire l'upgrade di Gradle quando esegui l'upgrade di AGP o di un altro plug-in Gradle. Altri plug-in Gradle: a volte l'API dei plug-in di Gradle cambia. Quando esegui l'upgrade di Gradle, controlla se sono disponibili upgrade dei plug-in che utilizzi. Kotlin e Java: alcune librerie e plug-in richiedono versioni minime di Kotlin o Java oppure vuoi sfruttare nuove funzionalità del linguaggio, API o miglioramenti delle prestazioni. Piattaforma Android: il Play Store richiede aggiornamenti regolari dell'SDK Android. Ti consigliamo di testare le nuove versioni dell'SDK Android il prima possibile. Alcuni upgrade dell'SDK richiedono modifiche all'applicazione, ad esempio nuove autorizzazioni o l'utilizzo di nuove API. Librerie: vuoi dare la priorità alle librerie in base alla loro vicinanza all'architettura complessiva? Le librerie correlate alla piattaforma e all'architettura, come AndroidX, cambiano spesso per sfruttare nuove funzionalità o aiutare ad astrarre i cambiamenti nella piattaforma. Esegui l'upgrade di queste librerie almeno ogni volta che esegui l'upgrade della piattaforma Android o di altre librerie correlate all'architettura. Altri upgrade delle librerie possono essere distribuiti o ritardati, a meno che tu non abbia bisogno di una nuova funzionalità o di correzioni di bug specifiche. Android Studio: mantieni aggiornato Android Studio per accedere alle funzionalità e alle correzioni di bug più recenti della piattaforma IntelliJ IDEA di base e agli strumenti per lavorare con gli SDK Android più recenti.
Strumenti disponibili	Esistono molti strumenti e plug-in disponibili per aiutarti con gli upgrade. Strumenti come Dependabot e Renovate eseguono l'upgrade automatico delle versioni della libreria nella build, ma assicurati di analizzare i risultati per verificare l'eventuale presenza di rischi.

Strategie per tipi specifici di upgrade

L'upgrade di alcuni tipi di dipendenze potrebbe avere un effetto a cascata, che richiede l'upgrade di altri tipi di dipendenze. Analizziamo le relazioni tra gli elementi build nell'articolo Interdipendenze tra strumenti e libreria.

Figura 1. Crea relazioni.

Quando esegui l'upgrade di ogni tipo di componente, considera l'impatto dell'upgrade su altri componenti della build.

Android Gradle Plugin (AGP)	Android Studio include un assistente per l'upgrade dell'AGP che può aiutarti a svolgere queste attività. Se utilizzi l'assistente o esegui l'upgrade manualmente, considera quanto segue: Consulta le note di rilascio dell'AGP. Esegui l'upgrade di Gradle almeno alla versione indicata. Esegui l'upgrade di Android Studio a una versione che supporti la versione di AGP scelta. Utilizza versioni di Android Studio e AGP che supportano l'SDK Android che vuoi usare. Verifica la compatibilità con SDK Build Tools, NDK e JDK. Se sviluppi un plug-in Gradle (per uso interno o pubblico) che estende o utilizza i dati di AGP, controlla se devi eseguire l'upgrade del plug-in. A volte AGP ritira e successivamente rimuove le API, causando incompatibilità con i plug-in precedenti.
Compilatore, linguaggio e runtime Kotlin	Consulta le note di rilascio di Kotlin per conoscere i problemi noti e le incompatibilità. Se utilizzi Jetpack Compose: Se la nuova versione di Kotlin è precedente alla 2.0.0: Individua il plug-in del compilatore Compose compatibile. Esegui l'upgrade di kotlinCompilerExtensionVersion in build.gradle.kts di tutti i moduli in cui viene visualizzato. Se la nuova versione di Kotin è 2.0.0 o successiva: Configura il plugin Gradle di Compose Compiler con la stessa versione del compilatore Kotlin. Se utilizzi Kotlin Symbol Processing (KSP), consulta la guida rapida di KSP per la configurazione e le release di KSP per le versioni disponibili. Tieni presente che devi utilizzare una versione del punto di forza principale che corrisponda alla versione di Kotlin. Ad esempio, se utilizzi Kotlin 2.0.21, puoi utilizzare qualsiasi versione del plug-in KSP che inizi con 2.0.21, ad esempio 2.0.21-1.0.25. In genere non è necessario eseguire l'upgrade dei processori KSP (ad esempio il compilatore Room, che viene visualizzato come dipendenza ksp nei file di compilazione); il plug-in KSP esegue l'astrazione di gran parte dell'API del compilatore e l'API KSP utilizzata dai processori è stabile. Esegui l'upgrade di tutti gli altri plug-in del compilatore Kotlin che utilizzi. L'API del plug-in del compilatore Kotlin cambia spesso tra una release e l'altra e i plug-in devono utilizzare un'API compatibile. Se il plug-in è elencato in Plug-in del compilatore, devi utilizzare la stessa versione del compilatore Kotlin. Per qualsiasi altro plug-in di compilazione, controlla la documentazione per la mappatura appropriata. Tieni presente che i plug-in del compilatore che non vengono gestiti insieme al compilatore Kotlin stesso spesso presentano ritardi di rilascio in attesa che l'API del plug-in del compilatore si stabilizzi. Prima di eseguire l'upgrade di Kotlin, verifica che per tutti i plug-in del compilatore che utilizzi siano disponibili upgrade corrispondenti. Infine, in alcuni casi, il linguaggio Kotlin cambia e devi aggiornare il codice. Questo accade più spesso se stai provando funzionalità sperimentali. Se il codice non viene compilato correttamente dopo l'upgrade del compilatore Kotlin, controlla se sono presenti modifiche alla lingua o interruzioni della libreria di runtime nelle note di rilascio di Kotlin.
Plug-in del compilatore Kotlin	Se devi eseguire l'upgrade di un plug-in del compilatore Kotlin, esegui l'upgrade alla versione corrispondente di Kotlin in uso. La maggior parte dei plug-in del compilatore Kotlin utilizza la stessa versione del compilatore Kotlin oppure inizia con la versione richiesta del compilatore Kotlin. Ad esempio, se la versione del plug-in è 2.0.21-1.0.25, devi utilizzare la versione 2.0.21 del compilatore Kotlin. La modifica della versione del compilatore Kotlin a volte richiede altre modifiche.
Biblioteche	Le librerie sono le dipendenze più aggiornate nella build. Vedrai gli upgrade disponibili nell'editor di Android Studio o se utilizzi alcuni strumenti e plug-in di dipendenza. Alcune librerie specificano un valore minimo di compileSdk o minSdk necessario per utilizzarle. Se non utilizzi almeno compileSdk specificato, le build non riescono. Tuttavia, il valore minSdk dell'applicazione viene impostato automaticamente sul massimo di tutti i valori minSdk specificati nelle dipendenze della libreria e nei file di compilazione. Alcune librerie specificano anche una versione minima di Kotlin da utilizzare. Aggiorna la versione di Kotlin nei file di compilazione in modo che sia almeno la versione specificata.
Gradle	A volte le nuove versioni di Gradle ritirano le API esistenti, rimuovendole in una release futura. Se sviluppi un plug-in Gradle, esegui l'upgrade il prima possibile, in particolare se è pubblico. Alcuni upgrade di Gradle richiedono la ricerca di nuove versioni dei plug-in che utilizzi. Tieni presente che lo sviluppo di questi plug-in può subire ritardi durante l'upgrade per adeguarli alle API dei plug-in Gradle più recenti. Per eseguire l'upgrade di Gradle: Leggi le note di rilascio relative alla versione che desideri utilizzare. Esegui l'upgrade della versione di Gradle in gradle/wrapper/gradle-wrapper.properties. Esegui l'upgrade del jar e degli script del wrapper Gradle eseguendo ./gradlew wrapper --gradle-version latest. Esegui l'upgrade dei plug-in Gradle. Esegui l'upgrade del JDK utilizzato per eseguire Gradle.
Plug-in Gradle	I plug-in Gradle sottoposti ad upgrade a volte utilizzano API Gradle nuove o modificate, che a loro volta richiedono un upgrade di Gradle o eventualmente modifiche alla loro configurazione nei file di compilazione. In entrambi i casi, vedrai avvisi o errori di compilazione che indicano l'incompatibilità. Ogni volta che esegui l'upgrade dei plug-in, esegui l'upgrade di Gradle.
SDK Android	Android Studio include un Assistente per l'upgrade dell'SDK Android che può aiutarti a svolgere queste attività. Se utilizzi l'assistente o esegui l'upgrade manualmente, tieni presente quanto segue: Ogni release dell'SDK Android contiene nuove funzionalità e API, correzioni di bug e modifiche al comportamento. Il Play Store richiede l'aggiornamento di targetSdk, ma ti consigliamo di aggiornare targetSdk prima delle scadenze per avere più tempo per apportare le modifiche necessarie. Prima di eseguire l'upgrade dell'SDK Android, leggi attentamente le note di rilascio. Presta particolare attenzione alla sezione relativa alle modifiche del comportamento, che include: Nuove autorizzazioni che dovrai richiedere durante l'installazione o il runtime. API ritirate e le relative sostituzioni. Modifiche non compatibili nelle API o nel comportamento. Nuove API Kotlin o Java, che potrebbero influire sul tuo codice. La sezione relativa alle modifiche del comportamento può essere piuttosto lunga, ma presta molta attenzione perché spesso contiene modifiche fondamentali che devi apportare alla tua applicazione. Per soddisfare i requisiti del Play Store, devi eseguire l'upgrade di targetSdk. L'upgrade di compileSdk è facoltativo e ti consente di accedere a nuove API. Tieni presente che alcune librerie, come AndroidX, includono un requisito minimo per compileSdk. Per sfruttare le nuove funzionalità dell'SDK durante lo sviluppo e garantire la compatibilità durante la compilazione, esegui l'upgrade del plug-in Android Gradle (AGP) e di Android Studio. Sono inclusi strumenti nuovi e migliorati per i nuovi SDK. Vedi Versioni minime degli strumenti per il livello API Android. Quando esegui l'upgrade dell'SDK Android, esegui l'upgrade di eventuali librerie AndroidX che utilizzi. AndroidX utilizza spesso API nuove e aggiornate per una migliore compatibilità e prestazioni nelle varie versioni dell'SDK Android.
Android Studio	Generalmente, puoi eseguire l'upgrade di Android Studio in qualsiasi momento. Potresti visualizzare messaggi che ti chiedono di eseguire l'upgrade di AGP o di eseguire l'upgrade dell'SDK Android. Questi upgrade sono vivamente consigliati, ma non obbligatori. Se in un secondo momento vuoi utilizzare Android Studio per eseguire l'upgrade di AGP o dell'SDK Android, puoi trovare queste opzioni nel menu Strumenti: Assistente all'upgrade di AGP… SDK Upgrade Assistant per Android…
Java	Se disponi di codice sorgente Java nella tua applicazione Android, puoi sfruttare le API Java più recenti. Ogni versione dell'SDK Android supporta un sottoinsieme di API Java e funzionalità del linguaggio. AGP fornisce compatibilità per le versioni precedenti dell'SDK Android tramite una procedura chiamata desugaring. Le note di rilascio dell'SDK Android specificano il livello Java supportato e i potenziali problemi. Alcuni di questi problemi potrebbero interessare anche il codice sorgente di Kotlin, in quanto Kotlin ha accesso alle stesse API Java. Assicurati di prestare molta attenzione alle sezioni dell'API JDK che appaiono nella sezione relativa alle modifiche del comportamento delle note di rilascio, anche se non disponi del codice sorgente Java. L'utilizzo di JDK è specificato in più punti negli script di compilazione. Per ulteriori informazioni, consulta la sezione Versioni Java nella compilazione Android.

Analisi dell'upgrade

L'upgrade di una dipendenza può comportare rischi sotto forma di modifiche all'API e al comportamento, nuovi requisiti di utilizzo, nuovi problemi di sicurezza o persino modifiche alla licenza. Ad esempio, devi:

• Vuoi cambiare il codice per le modifiche all'API?
• Vuoi aggiungere nuovi controlli delle autorizzazioni?
• Creare test aggiuntivi o modificare quelli esistenti per le modifiche del comportamento?

Tieni presente che la dipendenza di cui hai eseguito l'upgrade ha aggiornato le versioni delle sue dipendenze. Ciò può rapidamente generare un enorme insieme di modifiche.

Se utilizzi uno strumento come Renovate o Dependabot per automatizzare gli upgrade, tieni presente che non eseguono alcuna analisi per te; eseguono l'upgrade alle versioni più recenti delle librerie. Non assumere che tutto funzioni correttamente dopo questi tipi di upgrade automatici.

La chiave per gli upgrade di successo è l'analisi dell'upgrade:

1. Determina le differenze nelle dipendenze prima e dopo gli upgrade.
2. Esamina ogni modifica e determina i rischi.
3. Riduci i rischi o accetta o rifiuta le modifiche.

Determinare le differenze nelle dipendenze

Il primo passaggio dell'analisi di upgrade consiste nel determinare in che modo cambiano le dipendenze. Sfrutta il controllo della versione (VCS, come Git) e il plug-in Dependency Guard per visualizzare rapidamente le modifiche. Il tuo obiettivo è creare un'istantanea prima e dopo e confrontarle.

Configurare e creare la prima linea di base

Prima di iniziare l'upgrade, assicurati che il progetto venga compilato correttamente.

Idealmente, risolvi il maggior numero possibile di avvisi o crea basi di riferimento per monitorare gli avvisi che hai già visto.

• Lint: esamina gli avvisi lint esistenti e crea un base di riferimento per lint Android.
• Compilatore Kotlin:
  • Attiva -Werror per trattare tutti gli avvisi come errori. Consulta Come definire le opzioni.
  • Valuta la possibilità di utilizzare plug-in come Kotlin Warning Baseline o Kotlin Warnings Baseline Generator.
• Altri strumenti: se utilizzi altri strumenti di analisi statica (come Detekt) che supportano il monitoraggio del baseline, configura i relativi baseline.

Queste linee di base degli avvisi ti consentono di vedere più facilmente i nuovi avvisi introdotti durante l'upgrade delle dipendenze.

Crea una linea di base delle dipendenze configurando ed eseguendo Dependency Guard. Nel catalogo delle versioni gradle/libs.versions.toml, aggiungi:

[versions]
dependencyGuard = "0.5.0"

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

Aggiungi quanto segue al file di build dell'app:

Kotlin

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

dependencyGuard {
    configuration("releaseRuntimeClasspath")
}

Groovy

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

dependencyGuard {
    configuration('releaseRuntimeClasspath')
}

La configurazione releaseRuntimeClasspath è un target probabile, ma se vuoi utilizzare una configurazione diversa, esegui ./gradlew dependencyGuard senza una configurazione elencata nel file di build per visualizzare tutte le configurazioni disponibili.

Dopo la configurazione, esegui ./gradlew dependencyGuard per generare un report in app/dependencies/releaseRuntimeClasspath.txt. Questo è il report di riferimento. Esegui il commit nel tuo sistema di controllo della versione (VCS) per salvarlo.

Tieni presente che Dependency Guard acquisisce solo l'elenco delle dipendenze della biblioteca. Esistono altre dipendenze nei file di compilazione, ad esempio le versioni Android SDK e JDK. Se esegui il commit nel tuo VCS prima che le dipendenze cambino, la differenza del VCS evidenzia anche queste modifiche.

Esegui l'upgrade e confronta i dati con la base di riferimento

Dopo aver creato una base di riferimento, esegui l'upgrade delle dipendenze e di altre modifiche alla compilazione che volevi testare. A questo punto, non eseguire l'upgrade del codice sorgente o delle risorse.

Esegui ./gradlew lint per visualizzare i nuovi avvisi o errori di lint. Risolvi eventuali problemi importanti, quindi aggiorna la linea di base degli avvisi eseguendo ./gradlew lint -Dlint.baselines.continue=true. Se hai utilizzato altri strumenti per acquisire le linee di base degli avvisi, come Kotlin Warning Baseline o Kotlin Warnings Baseline Generator, risolvi i nuovi avvisi e aggiorna anche le relative linee di base.

Esegui ./gradlew dependencyGuard per aggiornare il report di riferimento. Quindi esegui il tuo VCS diff per vedere le modifiche non legate a librerie. È probabile che includa molti più upgrade della biblioteca di quanto pensi.

Analizza i rischi

Una volta che sai cosa è cambiato, considera i possibili rischi di ogni libreria aggiornata. In questo modo puoi concentrare i test o approfondire le modifiche. Definisci un insieme di rischi da analizzare per il tuo progetto per garantire un'analisi coerente.

Alcune considerazioni:

Aggiornamenti principali delle versioni	Il numero della versione principale è cambiato? Nel versionamento semantico, il primo numero è noto come versione principale. Ad esempio, se la versione di una libreria è stata aggiornata da 1.2.3 a 2.0.1, la versione principale è cambiata. In genere questo indica che lo sviluppatore della libreria ha apportato modifiche incompatibili tra le versioni, ad esempio ha rimosso o modificato parti dell'API. Quando vedi questo messaggio, presta particolare attenzione alle librerie interessate quando esamini una delle seguenti considerazioni. Se il codice utilizza API sperimentali (che spesso richiedono l'attivazione tramite annotazioni o specifiche del file di compilazione), anche le modifiche alle versioni minori o alle patch, ad esempio l'upgrade da 1.2.3 a 1.3.1 o da 1.2.3 a 1.2.5, potrebbero comportare rischi aggiuntivi.
API non stabile	Alcune release delle librerie potrebbero includere API non stabili. Di solito si tratta di API in fase di sviluppo o che dipendono da un'altra API instabile. Sebbene in genere siano limitate alle anteprime, come le release alpha, dev o sperimentali, alcune librerie includono API contrassegnate come sperimentali o instabili. Se possibile, evita API di questo tipo. Se hai bisogno di usarle, assicurati di registrarle e tieni d'occhio eventuali modifiche o rimozioni nelle release successive.
Comportamento dinamico	Alcune librerie si comportano in modo diverso in base a fattori esterni. Ad esempio, una libreria che comunica con un server dipende dalle modifiche apportate a quel server. La libreria deve corrispondere a una determinata versione del server? La libreria riesce a connettersi a versioni diverse di un server? Esiste qualche altro fattore esterno che influisce sul corretto comportamento della libreria?
Unione di manifest	Le librerie pubblicate come archivi Android (AAR) possono contenere risorse e manifest che vengono uniti nella tua applicazione. Queste possono aggiungere nuove autorizzazioni e componenti Android, come attività o broadcast receiver, che vengono eseguiti indirettamente.
Aggiornamenti di runtime	Alcune librerie utilizzano funzionalità che possono essere aggiornate al di fuori del controllo dell'applicazione. Una libreria potrebbe utilizzare Play Services, di cui viene eseguito l'upgrade indipendentemente dall'SDK Android. Altre librerie possono essere associate a servizi in applicazioni esterne aggiornate in modo indipendente (spesso utilizzando AIDL).
Quante versioni vuoi saltare?	Più a lungo aspetti per eseguire l'upgrade di una raccolta, maggiori sono i rischi potenziali. Se noti una versione che cambia in modo significativo, ad esempio da 1.2.3 a 1.34.5, presta particolare attenzione a questa libreria.
Guide alla migrazione	Controlla se la libreria dispone di una guida alla migrazione. Ciò può ridurre significativamente l’analisi del rischio e la pianificazione della mitigazione. Tieni presente che la presenza di questa guida è un buon indicatore del fatto che lo sviluppatore si è concentrato sulla compatibilità e ha preso in considerazione la mitigazione dell'upgrade.
Note di rilascio	Consulta le note di rilascio (se fornite) per ogni raccolta modificata. Cerca indicazioni di modifiche che comportano interruzioni o nuovi requisiti, ad esempio autorizzazioni aggiunte.
README	Alcuni file README di una libreria segnalano potenziali rischi, soprattutto se la libreria non fornisce note di rilascio. Cerca i _problemi noti_, in particolare quelli relativi alla sicurezza.
Verifica le vulnerabilità note	Play SDK Index monitora le vulnerabilità di molti SDK di uso comune. Play Console segnala se utilizzi uno degli SDK elencati con vulnerabilità note. Quando modifichi i file di compilazione in Android Studio, l'IDE controlla l'indice SDK e segnala l'utilizzo di versioni delle librerie vulnerabili. Il National Institute of Standards and Technology (NIST) gestisce un ampio National Vulnerability Database (NVD). Il plug-in Gradle Dependency Check controlla le dipendenze utilizzate rispetto al NVD. Per utilizzare Dependency Check, richiedi una chiave API NVD, configura il plug-in Gradle ed esegui ./gradlew dependencyCheckAnalyze. Tieni presente che l'esecuzione di questa operazione può richiedere molto tempo.
Conflitti di versione	Le versioni vengono risolte come previsto? Cerca conflitti, in particolare differenze sostanziali tra le versioni. Per informazioni dettagliate su come cercare i conflitti, consulta Risoluzione delle dipendenze a Gradle. In particolare, cerca -> nel report ./gradlew app:dependencies. Se possibile, collabora con gli autori di una dipendenza per risolvere i conflitti. Se la tua azienda lo consente, apporta modifiche alla libreria (upstreaming) per migliorare la compatibilità della libreria.
Controlla le licenze	Cerca le modifiche alle licenze quando esegui l'upgrade di una raccolta. La libreria stessa potrebbe passare a una licenza non più compatibile con la tua applicazione o libreria. Le nuove dipendenze transitive potrebbero anche introdurre licenze incompatibili. Per informazioni dettagliate su come controllare l'attuale insieme di licenze nelle dipendenze, consulta Convalidare le licenze.
Rischi relativi a manutenzione e qualità	Per le librerie con repository pubblici: Quanti collaboratori gestiscono la biblioteca? Quando è stato eseguito l'ultimo upgrade e con quale frequenza cambia la raccolta? Come si presenta la lista di problemi in attesa (se disponibile)? Dai un'occhiata per farti un'idea dei potenziali problemi e del debito tecnico della libreria. In che misura i test delle unità coprono la libreria? Esistono anti-pattern noti nel codebase? La raccolta è ben documentata? Ci sono molti commenti _fixme_ nel codice?
Open source e software proprietario	Se una libreria è open source, sarà più facile eseguire il debug dei problemi rispetto a quelli chiusi, indipendentemente dal fatto che siano nel codice o nel codice della libreria. Riduci al minimo le dipendenze closed source e applica ulteriori controlli durante la valutazione. Esistono valide alternative adatte al tuo caso d'uso? Quali accordi sul livello del servizio sono disponibili per le librerie closed source? Se scegli di utilizzare una dipendenza closed source, preparati a scrivere casi di test aggiuntivi per contribuire a limitare i rischi.

Esegui una build

Crea il progetto. Cerca nuovi errori o avvisi. Se riesci a identificare la libreria che li causa, prendi nota del rischio per l'upgrade della libreria.

Se visualizzi nuovi avvisi di deprezzamento, aggiungili come rischi specifici per la biblioteca che li genera. Questi possono essere rimossi nelle release successive. Se vuoi continuare a utilizzare la libreria, dedica del tempo alla conversione dall'utilizzo di API deprecate alle relative sostituzioni oppure prendi nota dei ritiri per tenere d'occhio queste funzioni e se vengono rimosse in un secondo momento.

Utilizzare lint per rilevare i problemi relativi all'API

Android lint può rilevare molti problemi nella tua applicazione, inclusi alcuni che sono il risultato della modifica delle versioni delle dipendenze o dell'SDK Android. Ad esempio, se esegui l'upgrade di compileSdk e utilizzi le sue nuove API, lint segnala quelle non disponibili nelle versioni precedenti dell'SDK.

Lint viene eseguito nell'editor di Android Studio e segnala i problemi man mano che apporti le modifiche. Tuttavia, in genere non viene eseguito nell'ambito della compilazione in Studio o quando esegui una compilazione da riga di comando, a meno che non utilizzi i target build o lint.

Se utilizzi l'integrazione continua (CI), esegui gradlew build o gradlew lint durante le build CI (o almeno durante le build notturne) per rilevare questi tipi di errori.

Se non utilizzi la CI, assicurati di eseguire gradlew lint almeno occasionalmente.

Nota: le regole di lint generali e a livello di SDK Android vengono fornite con AGP, mentre quelle specifiche per le librerie vengono pacchettizzate con le relative librerie. Mantieni AGP e le dipendenze delle librerie il più aggiornate possibile per assicurarti che al codice vengano applicate le regole lint più recenti. Questo è particolarmente importante per le nuove regole lint che sono state aggiunte o di cui è stato eseguito l'upgrade per una nuova versione dell'SDK Android.

Presta particolare attenzione agli errori e agli avvisi di lint. Alcune librerie vengono fornite con i propri controlli lint, contribuendo a garantire l'utilizzo corretto della loro API. Alcune nuove versioni di una libreria includono nuovi avvisi ed errori lint, che generano nuovi report al momento della creazione.

Riduci i rischi

Dopo aver determinato i rischi dell'upgrade, decidi come mitigarli:

• Accetta alcuni rischi così come sono. Alcuni rischi sono sufficientemente bassi da essere accettabili, soprattutto quando il tempo e le risorse per l'upgrade sono limitati.
• Rifiutare del tutto alcuni rischi. Alcuni upgrade potrebbero sembrare troppo rischiosi, soprattutto se al momento hai poco tempo o risorse per mitigarli. Se hai bisogno di una valutazione, concentrati sugli upgrade necessari per i bug che hai riscontrato o per le nuove funzionalità di cui hai bisogno.
• Riduci i rischi rimanenti
  • Valuta la possibilità di raggruppare gli upgrade in insiemi di modifiche più piccoli e indipendenti. In questo modo si riduce il rischio complessivo e si consente il rollback parziale.
  • Analizza le modifiche in dettaglio.
  • Esegui il test dell'app per verificare la presenza di modifiche inaspettate. Aggiungi nuovi test ove necessario per aumentare la sicurezza dell'upgrade.
  • Quando viene trovato qualcosa di discutibile, controlla la fonte (se disponibile).
  • Apporta le modifiche necessarie nel codice sorgente o nella compilazione.

Documenta le tue decisioni. Se i rischi di un upgrade diventano problemi durante l'esecuzione della tua applicazione, la documentazione dell'analisi dei rischi può ridurre l'analisi degli errori necessaria.

Convalidare le licenze

Gli sviluppatori delle librerie rilasciano le licenze per il tuo utilizzo. Devi rispettare i termini della licenza, altrimenti non potrai utilizzare la libreria. Alcune licenze sono molto permissive, spesso richiedono solo l'attribuzione della libreria e la visualizzazione del testo della licenza agli utenti finali. Alcune sono considerate virali. Se utilizzi queste librerie, devi applicare la stessa licenza alla tua applicazione o libreria.

Le licenze possono cambiare con ogni release. Ogni volta che esegui l'upgrade, devi verificare che le dipendenze che utilizzi siano concesse in licenza in modo compatibile con la tua applicazione o libreria.

Se una licenza non è compatibile (o è stata modificata in modo da non essere più compatibile), non puoi utilizzare quella versione della libreria. Puoi:

• Contatta il proprietario della raccolta e richiedi il proseguimento della licenza esistente o la licenza doppia per continuare a consentire la vecchia licenza.
• Collabora con il tuo team legale per stabilire se puoi modificare la licenza in modo che sia compatibile.
• Trova un'altra libreria con una licenza compatibile e modifica l'applicazione come necessario.
• Esegui il fork dell'ultima versione compatibile della libreria (se la licenza consente derivati e le modifiche non sono retroattive) e apporta le tue modifiche.