Fazer upgrade das versões de dependência

O upgrade das dependências oferece acesso aos recursos mais recentes, correções de bugs e melhorias. Para fazer upgrade das dependências, você precisa entender como o Gradle resolve as versões solicitadas, os riscos envolvidos e as etapas que podem ser tomadas para mitigá-los.

Considere sua estratégia de upgrade

A etapa mais importante de qualquer upgrade é a análise de risco. Determine o quanto você se sente confortável com cada dependência que você atualiza. Há muitas considerações ao definir sua estratégia de upgrade, incluindo:

Criar uma biblioteca

Você está criando um aplicativo que os usuários baixam e executam em um dispositivo? Ou você está criando uma biblioteca para ajudar outros desenvolvedores a criar aplicativos?

Ao criar um aplicativo, o foco é mantê-lo atualizado e estável.

Se você estiver criando uma biblioteca, seu foco deve ser nos aplicativos de outros desenvolvedores. Seus upgrades afetam os consumidores. Se você fizer upgrade de uma das dependências, essa versão se tornará um candidato para a resolução de dependências do Gradle, possivelmente interrompendo o uso dessa dependência pelo aplicativo.

Primeiro, minimize as dependências da biblioteca sempre que possível. Quanto menos dependências você tiver, menor será o impacto na resolução de dependências do consumidor.

Siga o versionamento semântico para indicar os tipos de mudanças que você está fazendo. Por exemplo, o AndroidX segue o controle de versões semânticas e adiciona um esquema de controle de versões de pré-lançamento. Evite upgrades de versão do major para não prejudicar os consumidores.

Considere criar um candidato à versão (RC) da sua biblioteca para que os usuários testem com antecedência.

Consulte Diretrizes de compatibilidade com versões anteriores para autores de bibliotecas para ver detalhes sobre como manter a interface binária do aplicativo (ABI, na sigla em inglês) compatível. Use testes de integração e ferramentas como o validador de compatibilidade binária para garantir que as mudanças de ABI correspondam à mudança de versão pretendida.

Se você lançar correções em uma patch para versões anteriores da biblioteca, os consumidores não precisarão fazer upgrade para a próxima versão major ou minor, a menos que queiram novos recursos. Evite fazer upgrade de dependências transitivas nesses upgrades.

Se o upgrade da biblioteca exigir mudanças que possam ser particularmente difíceis para os consumidores, considere lançá-las como um novo artefato para que as versões antigas e novas possam coexistir e permitir um lançamento mais gradual.

Observação: se um upgrade de uma das suas dependências contiver uma mudança importante na API, provavelmente será necessário fazer o upgrade em uma versão major ou minor e fazer as mudanças necessárias. Se você não fizer isso, os usuários da biblioteca poderão fazer isso, causando incompatibilidades entre a biblioteca e essa dependência. Isso pode acontecer mesmo que não haja mudanças na sua biblioteca. Você pode lançar uma nova versão apenas para atualizar essa dependência.

Ciclo de lançamento

Com que frequência você lança seu aplicativo ou biblioteca?

Ciclos de desenvolvimento e lançamento mais curtos

  • Há menos tempo para fazer upgrade.
  • Você pode ficar para trás rapidamente.
  • Pequenos upgrades frequentes podem facilitar a carga de trabalho.
  • Se um upgrade de biblioteca se tornar problemático, você poderá reverter esse upgrade mais rapidamente.
  • Ferramentas como Dependabot e Renovate diminuem a carga de trabalho, mas é importante analisar os resultados para verificar se há riscos.

Ciclos de desenvolvimento e lançamento mais longos

  • Há mais tempo para fazer e testar upgrades.
  • É mais provável que as versões mais recentes das dependências sejam lançadas durante o ciclo.
  • Reverter atualizações e lançar o aplicativo ou a biblioteca leva mais tempo.

Acompanhe os recursos mais recentes

Você prefere usar os recursos e APIs mais recentes ou só faz upgrade quando precisa de um recurso ou correção de bug?

Considere as vantagens e desvantagens de upgrades frequentes. Os upgrades futuros são mais fáceis (menos mudanças para integrar), mas você corre mais riscos de upgrade com mais frequência.

Testar upgrades para versões de pré-lançamento (alfa, beta, candidato a lançamento) de bibliotecas pode ajudar na preparação quando as versões estáveis estiverem disponíveis.

Nova dependência

Se você estiver adicionando uma nova dependência, considere um processo de análise rigoroso que examine a biblioteca em relação a todos os critérios de risco para garantir que eles foram avaliados corretamente. Não permita que novas dependências sejam adicionadas sem revisão.

Equipe dedicada

Você tem uma equipe de build dedicada? Seus engenheiros de software fazem a manutenção do build? Uma equipe dedicada geralmente pode passar mais tempo analisando os riscos de upgrade e testando novas versões para garantir que o build funcione corretamente antes que os engenheiros usem as novas versões.

Tipo de upgrade

Alguns upgrades são mais importantes que outros. Pense nas que são mais importantes para você.

As atualizações de ferramentas de build, como o Gradle e os plug-ins do Gradle, geralmente têm um impacto menor para os usuários, e grande parte do risco é interno ao build. O build em si ajuda a validar essas mudanças. Os upgrades da biblioteca e do SDK são mais difíceis de validar e apresentam um risco maior para os usuários.

Plug-in do Android para Gradle (AGP): a ferramenta usada para criar a biblioteca ou o aplicativo Android. Esse é o upgrade mais importante que você pode fazer, já que ele geralmente inclui ou ativa melhorias de desempenho, correções de bugs, novas regras de lint e suporte a novas versões da Plataforma Android.

Gradle: muitas vezes, você vai precisar fazer upgrade do Gradle ao atualizar o AGP ou outro plug-in do Gradle.

Outros plug-ins do Gradle: às vezes, a API do plug-in do Gradle muda. Ao fazer upgrade do Gradle, verifique se há upgrades para os plug-ins que você usa.

Kotlin e Java: algumas bibliotecas e plug-ins exigem versões mínimas do Kotlin ou do Java, ou você quer aproveitar novos recursos da linguagem, APIs ou melhorias de desempenho.

Plataforma Android: a Play Store exige atualizações regulares do SDK do Android. Teste as novas versões do SDK do Android assim que possível. Alguns upgrades do SDK exigem mudanças no app, como novas permissões ou o uso de novas APIs.

Bibliotecas: você quer priorizar as bibliotecas com base na proximidade delas em relação à arquitetura geral?

  • Bibliotecas relacionadas à plataforma e à arquitetura, como o AndroidX, geralmente mudam para aproveitar novos recursos ou ajudar a abstrair mudanças na plataforma. Faça upgrade dessas bibliotecas sempre que atualizar a plataforma Android ou outras bibliotecas relacionadas à arquitetura.
  • Outros upgrades de biblioteca podem ser espalhados ou adiados, a menos que você precise de um novo recurso ou correções de bugs específicas.

Android Studio: manter o Android Studio atualizado dá acesso aos recursos e correções de bugs mais recentes na plataforma e nas ferramentas do IntelliJ IDEA para trabalhar com os SDKs mais recentes do Android.

Ferramentas disponíveis

Há muitas ferramentas e plug-ins disponíveis para ajudar nos upgrades. Ferramentas como Dependabot e Renovate atualizam automaticamente as versões da biblioteca no seu build, mas analise os resultados para verificar se há riscos.

Estratégias para tipos específicos de upgrades

O upgrade de alguns tipos de dependências pode ter um efeito em cascata, exigindo que outros tipos de dependências sejam atualizados. Discutimos as relações entre elementos de build em Dependências entre ferramentas e bibliotecas.

Criar dependências e relacionamentos
Figura 1. Construa relacionamentos.

Ao fazer upgrade de cada tipo de componente, considere como o upgrade afeta outros componentes no build.

Plug-in do Android para Gradle (AGP)

O Android Studio inclui um assistente de upgrade do AGP que pode ajudar com essas tarefas.

Se você usar o assistente ou realizar o upgrade manualmente, considere o seguinte:

Consulte as notas da versão do AGP.

Faça upgrade do Gradle para pelo menos a versão listada.

Faça upgrade do Android Studio para uma versão compatível com a versão do AGP escolhida.

Use versões do Android Studio e do AGP que ofereçam suporte ao SDK do Android que você quer usar.

Verifique a compatibilidade com o SDK Build Tools, o NDK e o JDK.

Se você desenvolver um plug-in do Gradle (para uso interno ou público) que estende ou usa dados do AGP, verifique se é necessário fazer upgrade dele. Às vezes, o AGP descontinua e depois remove APIs, causando incompatibilidades com plug-ins anteriores.

Compilador, linguagem e ambiente de execução do Kotlin

Verifique as notas da versão do Kotlin para conferir problemas e incompatibilidades conhecidos.

Se você usa o Jetpack Compose:

Se você usa o processamento de símbolos (KSP, na sigla em inglês) do Kotlin, consulte o Guia de início rápido do KSP para configuração e as versões do KSP (links em inglês) para conferir as versões disponíveis. É necessário usar uma versão do KSP que corresponda à versão do Kotlin. Por exemplo, se você estiver usando o Kotlin 2.0.21, poderá usar qualquer versão do plug-in KSP que comece com 2.0.21, como 2.0.21-1.0.25. Normalmente, não é necessário fazer upgrade dos processadores da KSP, como o compilador do Room, que aparece como uma dependência ksp nos arquivos de build. O plug-in da KSP abstrai grande parte da API do compilador, e a API da KSP usada pelos processadores é estável.

Faça upgrade de todos os outros plug-ins do compilador Kotlin que você está usando. A API do plug-in do compilador Kotlin muda com frequência entre as versões, e os plug-ins precisam usar uma API compatível. Se o plug-in estiver listado em Plug-ins do compilador, use a mesma versão do compilador Kotlin. Para outros plug-ins de compilação, verifique a documentação deles para saber o mapeamento adequado.

Os plug-ins do compilador que não são mantidos com o próprio compilador Kotlin geralmente apresentam atrasos no lançamento enquanto aguardam a estabilização da API do plug-in do compilador. Antes de fazer upgrade do Kotlin, verifique se todos os plug-ins do compilador que você usa têm upgrades correspondentes disponíveis.

Por fim, em algumas ocasiões, o idioma Kotlin muda, exigindo que você atualize o código. Isso geralmente acontece se você estiver testando recursos experimentais. Se o código não for criado corretamente após a atualização do compilador Kotlin, verifique se há mudanças de linguagem ou quebras de biblioteca no release notes do Kotlin.

Plug-ins do compilador Kotlin

Se você precisar fazer upgrade de um plug-in do compilador do Kotlin, faça upgrade para a versão correspondente do Kotlin que está sendo usada.

A maioria dos plug-ins do compilador Kotlin usa a mesma versão do compilador Kotlin ou começa com a versão necessária do compilador Kotlin. Por exemplo, se a versão do plug-in for 2.0.21-1.0.25, use a versão 2.0.21 do compilador Kotlin.

Às vezes, a mudança da versão do compilador Kotlin exige outras alterações.

Bibliotecas

As bibliotecas são a dependência mais comumente atualizada no build. Você vai ver as atualizações disponíveis no editor do Android Studio ou se usar algumas ferramentas de dependência e plug-ins.

Algumas bibliotecas especificam um compileSdk ou minSdk mínimo necessário para usar a biblioteca. Se você não usar pelo menos o compileSdk especificado, seus builds vão falhar. No entanto, o minSdk do aplicativo é definido automaticamente como o máximo de todos os valores de minSdk especificados nas dependências de biblioteca e nos arquivos de build.

Algumas bibliotecas também especificam uma versão mínima do Kotlin para uso. Atualize a versão do Kotlin nos arquivos de build para que ela seja pelo menos a especificada.

Gradle

Às vezes, novas versões do Gradle descontinuam as APIs existentes, removendo essas APIs em uma versão futura. Se você desenvolver um plug-in do Gradle, faça o upgrade dele o mais rápido possível, especialmente se ele for público.

Alguns upgrades do Gradle exigem a localização de novas versões dos plug-ins que você usa. Esses plug-ins podem ter atrasos no desenvolvimento à medida que são atualizados para corresponder às APIs do plug-in do Gradle mais recentes.

Para fazer upgrade do Gradle:

  • Leia as notas da versão que você quer usar.
  • Faça upgrade da versão do Gradle no gradle/wrapper/gradle-wrapper.properties.
  • Faça upgrade do jar do wrapper do Gradle e dos scripts executando ./gradlew wrapper --gradle-version latest.
  • Faça upgrade dos plug-ins do Gradle.
  • Faça upgrade do JDK usado para executar o Gradle.

Plug-ins do Gradle

Plug-ins atualizados do Gradle às vezes usam APIs novas ou alteradas do Gradle, que exigem um upgrade do Gradle ou talvez mudanças na configuração nos arquivos de build. Em ambos os casos, você verá avisos ou erros de build que indicam a incompatibilidade.

Sempre que fizer upgrade de plug-ins, faça upgrade do Gradle.

SDK do Android

O Android Studio inclui um assistente para upgrade do SDK do Android que pode ajudar com essas tarefas.

Se você usar o assistente ou realizar o upgrade manualmente, considere o seguinte:

Cada versão do SDK do Android contém novos recursos e APIs, correções de bugs e mudanças de comportamento. A Play Store exige a atualização do targetSdk, mas considere atualizar o targetSdk antes dos prazos para ter mais tempo para fazer as mudanças necessárias.

Antes de fazer upgrade do SDK do Android, leia com atenção as notas da versão. Preste atenção à seção de mudanças de comportamento, que inclui:

  • Novas permissões que você vai precisar solicitar no momento da instalação ou da execução.
  • APIs descontinuadas e as substituições delas.
  • Mudanças interruptivas em APIs ou comportamento.
  • Novas APIs Kotlin ou Java, que podem afetar seu código.

A seção de mudanças de comportamento pode ser longa, mas preste muita atenção, porque ela geralmente contém mudanças críticas que você precisa fazer no aplicativo.

Você precisa fazer upgrade do targetSdk para atender aos requisitos da Play Store. O upgrade do compileSdk é opcional e dá acesso a novas APIs. Algumas bibliotecas, como o AndroidX, incluem um requisito mínimo de compileSdk.

Para aproveitar os novos recursos do SDK durante o desenvolvimento e garantir a compatibilidade durante o build, faça upgrade do Plug-in do Android para Gradle (AGP) e do Android Studio. incluindo ferramentas novas e aprimoradas para novos SDKs. Consulte Versões mínimas de ferramentas para um nível da API do Android.

Ao fazer upgrade do SDK do Android, atualize todas as bibliotecas do AndroidX que você usa. O AndroidX usa APIs novas e atualizadas com frequência para oferecer melhor compatibilidade e desempenho entre as versões do SDK do Android.

Android Studio

Geralmente, é possível fazer upgrade do Android Studio a qualquer momento. Talvez você receba mensagens solicitando que faça upgrade do AGP ou do SDK do Android. Esses upgrades são altamente recomendados, mas não obrigatórios.

Se mais tarde você quiser usar o Android Studio para fazer upgrade do AGP ou do SDK do Android, encontre estas opções no menu Ferramentas:

Java

Se você tiver um código-fonte Java no seu aplicativo Android, aproveite as APIs Java mais recentes.

Cada versão do SDK do Android oferece suporte a um subconjunto de APIs do Java e recursos de linguagem. O AGP oferece compatibilidade com versões anteriores do SDK do Android usando um processo chamado desugaring.

As notas da versão do SDK do Android especificam qual nível do Java é compatível e quais são os possíveis problemas. Algumas dessas questões também podem afetar o código-fonte do Kotlin, porque ele tem acesso às mesmas APIs Java. Preste muita atenção às seções da API JDK que aparecem na seção de alterações comportamentais das notas de versão, mesmo que você não tenha o código-fonte em Java.

O uso do JDK é especificado em vários lugares nos scripts de build. Consulte Versões Java no build do Android para mais informações.

Análise de upgrade

Atualizar uma dependência pode introduzir riscos na forma de mudanças de API e comportamento, novos requisitos de uso, novos problemas de segurança ou até mesmo mudanças de licença. Por exemplo, você precisa:

  • Mudar o código para mudanças na API?
  • Adicionar novas verificações de permissão?
  • Criar outros testes ou modificar os atuais para mudanças de comportamento?

Considere que a dependência atualizada atualizou as versões das dependências dela. Isso pode se transformar rapidamente em um conjunto enorme de mudanças.

Se você usa uma ferramenta como o Renovate ou o Dependabot para automatizar os upgrades, saiba que elas não fazem nenhuma análise para você. Elas fazem upgrade para as versões mais recentes da biblioteca. Não presumir que tudo vai funcionar corretamente após esses tipos de upgrade automático.

A chave para upgrades bem-sucedidos é a análise de upgrade:

  1. Determine as diferenças de dependência antes e depois dos upgrades.
  2. Examinar cada mudança e determinar os riscos envolvidos.
  3. Mitigar riscos ou aceitar ou rejeitar mudanças.

Determinar diferenças de dependência

A primeira etapa da sua análise de upgrade é determinar como suas dependências mudam. Aproveite o controle de versão (VCS, como o Git) e o plug-in Dependency Guard para conferir rapidamente as mudanças. Seu objetivo é criar um snapshot de antes e depois e compará-los.

Configurar e criar sua primeira linha de base

Antes de iniciar o upgrade, confira se o projeto foi criado.

O ideal é resolver o maior número possível de avisos ou criar valores de referência para acompanhar os avisos que você já recebeu.

Esses valores de referência de alerta facilitam a visualização de novos avisos introduzidos ao atualizar as dependências.

Crie um valor de referência de dependência configurando e executando o Dependency Guard. No catálogo de versões do gradle/libs.versions.toml, adicione:

[versions]
dependencyGuard = "0.5.0"

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

E adicione o seguinte ao arquivo de build do app:

Kotlin

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

dependencyGuard {
    configuration("releaseRuntimeClasspath")
}

Groovy

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

dependencyGuard {
    configuration('releaseRuntimeClasspath')
}

A configuração releaseRuntimeClasspath é um possível destino, mas, se você quiser usar uma configuração diferente, execute ./gradlew dependencyGuard sem uma configuração listada no arquivo de build para ver todas as configurações disponíveis.

Após a configuração, execute ./gradlew dependencyGuard para gerar um relatório em app/dependencies/releaseRuntimeClasspath.txt. Este é seu relatório de valor de referência. Confirme isso no seu sistema de controle de versões (VCS, na sigla em inglês) para salvar.

O Dependency Guard só captura a lista de dependências de biblioteca. Há outras dependências nos arquivos de build, como as versões do SDK do Android e do JDK. Confirmar no VCS antes das mudanças de dependência permite que o VCS diff destaque essas mudanças também.

Faça upgrade e compare com o valor de referência

Depois de ter uma referência, atualize as dependências e outras mudanças de build que você queria testar. Não faça upgrade do código-fonte ou dos recursos neste momento.

Execute ./gradlew lint para conferir novos avisos ou erros de lint. Resolva problemas importantes e atualize o valor de referência do aviso executando ./gradlew lint -Dlint.baselines.continue=true. Se você usou outras ferramentas para capturar valores de referência de aviso, como o Baseline de aviso do Kotlin ou o Gerador de valores de referência de avisos do Kotlin, resolva novos avisos e atualize os valores de referência.

Execute ./gradlew dependencyGuard para atualizar o relatório de referência. Em seguida, execute o diferencial do VCS para conferir as mudanças que não são de biblioteca. É provável que ele inclua muitas mais atualizações de biblioteca do que você imaginava.

Analisar riscos

Depois de saber o que mudou, considere os possíveis riscos de cada biblioteca atualizada. Isso ajuda a concentrar seus testes ou a investigar mais profundamente as mudanças. Defina um conjunto de riscos a serem analisados em seu projeto para garantir uma análise consistente.

Algumas considerações:

Atualizações de versão principal

O número da versão principal mudou?

No controle de versões semântico, o primeiro número é conhecido como a versão principal. Por exemplo, se a versão de uma biblioteca foi atualizada de 1.2.3 para 2.0.1, a versão principal foi alterada. Isso geralmente indica que o desenvolvedor da biblioteca fez mudanças incompatíveis entre as versões, como remover ou alterar partes da API.

Quando isso acontecer, preste atenção especial às bibliotecas afetadas ao analisar qualquer uma das considerações a seguir.

Se seu código usa APIs experimentais (que geralmente exigem que você ative usando anotações ou especificações do arquivo de build), até mesmo pequenas mudanças na versão de patch, como o upgrade da 1.2.3 para a 1.3.1 ou da 1.2.3 para a 1.2.5, podem apresentar riscos adicionais.

API Nonstable

Algumas versões de biblioteca podem incluir APIs não estáveis. Geralmente, são APIs que estão em andamento ou dependem de outra API instável.

Embora normalmente sejam limitadas a versões de pré-lançamento, como versões alfa, de desenvolvimento ou experimentais, algumas bibliotecas incluem APIs marcadas como experimentais ou instáveis.

Se possível, evite essas APIs. Se precisar usá-los, registre seu uso e monitore alterações ou remoções em versões posteriores.

Comportamento dinâmico

Algumas bibliotecas se comportam de maneira diferente com base em fatores externos. Por exemplo, uma biblioteca que se comunica com um servidor depende de mudanças nesse servidor.

  • A biblioteca precisa corresponder a uma determinada versão do servidor?
  • A biblioteca pode se conectar a diferentes versões de um servidor?
  • Algum outro fator externo afeta o comportamento adequado da biblioteca?

Mesclagem de manifesto

As bibliotecas publicadas como arquivos Android (AARs) podem conter recursos e manifestos que são mesclados no aplicativo. Eles podem adicionar novas permissões e componentes do Android, como atividades ou broadcast receivers, que são executados indiretamente.

Atualizações do ambiente de execução

Algumas bibliotecas usam recursos que podem ser atualizados fora do controle do seu aplicativo. Uma biblioteca pode usar o Google Play Services, que é atualizado independentemente do SDK do Android. Outras bibliotecas podem se vincular a serviços em aplicativos externos atualizados de forma independente (geralmente usando o AIDL).

Quantas versões você está pulando?

Quanto mais você esperar para fazer upgrade de uma biblioteca, maiores serão os riscos. Se você notar uma mudança significativa na versão, como de 1.2.3 para 1.34.5, preste atenção especial a essa biblioteca.

Guias de migração

Verifique se a biblioteca tem um guia de migração. Isso pode reduzir significativamente a análise de risco e o planejamento de mitigação.

A presença desse guia é um bom indicador de que o desenvolvedor se concentrou na compatibilidade e considerou sua mitigação de upgrade.

Notas da versão

Consulte as notas da versão (se fornecidas) de cada biblioteca alterada. Procure indicações de mudanças interruptivas ou novos requisitos, como permissões adicionadas.

READMEs

Alguns arquivos README de uma biblioteca mencionam riscos em potencial, especialmente se a biblioteca não tiver notas da versão. Procure _problemas conhecidos_, especialmente problemas de segurança.

Verificar vulnerabilidades conhecidas

O SDK Index do Google Play rastreia vulnerabilidades de muitos SDKs conhecidos. O Play Console informa se você usa um dos SDKs listados com vulnerabilidades conhecidas. Ao editar arquivos de build no Android Studio, o ambiente de desenvolvimento integrado verifica o índice do SDK e sinaliza o uso de versões de biblioteca vulneráveis.

O Instituto Nacional de Padrões e Tecnologia (NIST) mantém um grande Banco de dados Nacional de Vulnerabilidades (NVD, na sigla em inglês). O plug-in do Gradle Dependency Check verifica as dependências usadas em relação ao NVD.

Para usar a verificação de dependência, solicite uma chave de API do NVD, configure o plug-in para Gradle e execute ./gradlew dependencyCheckAnalyze. Essa execução pode levar muito tempo.

Conflitos de versão

As versões estão sendo resolvidas como esperado? Procure conflitos, especialmente diferenças de versão importantes. Consulte Resolução de dependências do Gradle para saber como procurar conflitos. Em particular, procure -> no relatório ./gradlew app:dependencies.

Sempre que possível, trabalhe com os autores de uma dependência para resolver conflitos. Se a sua empresa permitir, contribua com mudanças na biblioteca (upstreaming) para ajudar a melhorar a compatibilidade dela.

Verificar licenças

Procure mudanças nas licenças ao fazer upgrade de uma biblioteca. A biblioteca pode mudar para uma licença que não é mais compatível com seu aplicativo ou biblioteca. Novas dependências transitivas também podem introduzir licenças incompatíveis. Consulte Validar licenças para saber como verificar o conjunto atual de licenças nas dependências.

Riscos de manutenção e
qualidade

Para bibliotecas com repositórios públicos:

  • Quantos colaboradores fazem a manutenção da biblioteca?
  • Quando foi a última atualização e com que frequência a biblioteca muda?
  • Como é o backlog do problema (se disponível)? Leia rapidamente para ter uma ideia dos possíveis problemas e da dívida técnica da biblioteca.
  • Os testes de unidade cobrem bem a biblioteca?
  • Existem antipadrões conhecidos na base de código?
  • A biblioteca está bem documentada?
  • Existem muitos comentários _fixme_ na base de código?

Código aberto versus código fechado

Se uma biblioteca for de código aberto, será mais fácil depurar problemas do que com código fechado, estejam os problemas no código ou no da biblioteca.

Minimize as dependências de código fechado e aplique escrutínio adicional durante sua avaliação. Há boas alternativas que se encaixam no seu caso de uso? Quais contratos de nível de serviço estão disponíveis para bibliotecas de código fechado? Se você optar por usar uma dependência de código fechado, prepare-se para escrever outros casos de teste para ajudar a limitar os riscos.

Executar um build

Crie o projeto. Procure novos erros ou avisos. Se você conseguir identificar qual biblioteca está causando o problema, considere isso como um risco para o upgrade dessa biblioteca.

Se você notar novos avisos de depreciação, adicione esses avisos como riscos específicos para a biblioteca que os produz. Eles podem ser removidos em versões posteriores. Se você quiser continuar usando essa biblioteca, dedique tempo para converter o uso de APIs descontinuadas para as substituições ou observe as descontinuações para ficar de olho nessas funções e saber se elas serão removidas mais tarde.

Usar o lint para detectar problemas de API

O Android lint pode detectar muitos problemas no seu app, incluindo alguns que são resultado da alteração de versões de dependências ou do SDK do Android. Por exemplo, se você fizer upgrade do compileSdk e usar as novas APIs, o lint vai informar as que não estão disponíveis nas versões anteriores do SDK.

O lint é executado no editor do Android Studio e informa os problemas à medida que você faz mudanças. Mas normalmente não é executado como parte do build no Studio ou quando você executa um build de linha de comando, a menos que você use as metas build ou lint.

Se você usa a integração contínua (CI, na sigla em inglês), execute gradlew build ou gradlew lint durante os builds de CI (ou pelo menos nos builds diários) para detectar esses tipos de erros.

Se você não usar a CI, execute gradlew lint pelo menos ocasionalmente.

Preste atenção especial aos erros e avisos de lint. Algumas bibliotecas são enviadas com as próprias verificações de lint, ajudando a garantir o uso adequado da API. Algumas novas versões de uma biblioteca incluem novos avisos e erros de lint, resultando em novos relatórios durante o build.

Mitigar riscos

Depois de determinar os riscos de upgrade, decida como você quer mitigá-los:

  • Aceite alguns riscos como estão. Alguns riscos são baixos o suficiente para serem aceitáveis, especialmente quando o tempo e os recursos de upgrade são limitados.
  • Rejeitar alguns riscos de forma absoluta. Alguns upgrades podem parecer muito arriscados, especialmente se você tiver tempo ou recursos limitados para mitigá-los neste momento. Se você precisar fazer uma triagem, concentre-se nos upgrades necessários para bugs encontrados ou novos recursos necessários.
  • Mitigar os riscos restantes
    • Considere agrupar os upgrades em conjuntos de mudanças menores e independentes. Isso reduz o risco geral e permite a reversão parcial.
    • Investigue as mudanças em detalhes.
    • Teste o app para verificar se há mudanças inesperadas. Adicione novos testes quando necessário para aumentar a confiança no upgrade.
    • Verifique a fonte (se disponível) quando algo questionável for encontrado.
    • Faça as mudanças necessárias na origem ou no build.

Documente suas decisões. Se os riscos de um upgrade se tornarem problemas durante a execução do aplicativo, a documentação da análise de risco poderá reduzir a análise de erros necessária.

Validar licenças

Os desenvolvedores de bibliotecas licenciam as bibliotecas para seu uso. Você precisa cumprir os termos da licença ou não poderá usar a biblioteca. Algumas licenças são muito permissivas, muitas vezes exigindo apenas a atribuição da biblioteca e exibindo o texto da licença para os usuários finais. Algumas são consideradas virais. Se você usar essas bibliotecas, precisará aplicar a mesma licença ao seu aplicativo ou biblioteca.

As licenças podem mudar a qualquer momento. Sempre que você fizer upgrade, verifique se as dependências que você está usando estão licenciadas de maneira compatível com seu aplicativo ou biblioteca.

Se uma licença não for compatível (ou tiver mudado para não ser mais compatível), não será possível usar essa versão da biblioteca. Você pode:

  • Entre em contato com o proprietário da biblioteca e peça a continuação da licença atual ou do licenciamento duplo para manter a licença antiga.
  • Trabalhe com sua equipe jurídica para determinar se você pode mudar sua licença para que ela seja compatível.
  • Encontre outra biblioteca com uma licença compatível e modifique seu aplicativo conforme necessário.
  • Faça um fork da última versão compatível da biblioteca (se a licença permitir derivados e as mudanças não forem retroativas) e faça suas próprias mudanças.