Atualizar dependência com segurança

Atualizar uma dependência com segurança

Objetivo: mover uma dependência (ou um grupo fortemente acoplado) para uma versão mais nova, com as quebras compreendidas antecipadamente, não descobertas depois.

Planejamento

1. Identificar o estado atual. Descubra a versão instalada (lockfile, não apenas o manifest) e a versão alvo. Se o usuário disser "última", consulte o gerenciador de pacotes (npm view <pkg> version, pip index versions <pkg>, cargo search, etc.) e informe o número.
2. Registrar uma linha de base em uma árvore de trabalho limpa: instalar, compilar, testar, lint, verificação de tipos. Anote quaisquer falhas pré-existentes para não culpar o upgrade por elas.
3. Ler as notas de versão reais. Abra o changelog, notas de lançamento ou guia de migração para cada versão entre a atual e a alvo. Extraia: mudanças disruptivas, APIs removidas ou renomeadas, novas versões mínimas de runtime, defaults alterados, depreciações. Cite o link de origem de cada item. Se não encontrar notas de versão, informe e trate o upgrade como de alto risco.
4. Mapear o impacto. Use rg no código fonte para cada API removida, renomeada ou alterada. Liste os arquivos afetados antes de editar.

Execução

• Atualize apenas esta dependência (e peers necessários). Não execute uma "atualização geral".
• Atualize o manifest e lockfile com o gerenciador de pacotes do projeto, não manualmente.
• Faça as alterações de código exigidas pelas notas, começando pelas menores. Substitua usos depreciados quando a nova forma for equivalente.
• Execute instalação, compilação, testes, lint e verificação de tipos novamente. Compare com a linha de base.
• Para versões principais, execute também o aplicativo ou o caminho de exemplo principal, se possível, e verifique o tamanho do bundle, avisos de inicialização e avisos de depreciação.
• Se o upgrade precisar de um aumento de versão mínima de runtime ou peer, pare e pergunte antes de alterar.

Relatório

Upgrade: <pkg> <de> -> <para>
Fontes: <links do changelog>
Mudanças disruptivas aplicadas: <lista com referências de arquivos>
Alterações feitas: <resumo>
Verificação: <comandos, linha de base vs. resultado>
Avisos ou acompanhamentos: <depreciações, itens ignorados, riscos>
Rollback: reverta <arquivos>, ou `git revert <commit>`

Regras

• Nunca atualize e refatore na mesma alteração.
• Nunca pule um teste que falha ou afrouxe uma faixa de versão para esconder um problema.
• Correções de segurança: informe qual advisory o upgrade resolve apenas se você o viu em um advisory oficial ou nas notas de versão.
• Se uma dependência transitória causar conflito, mostre a saída do conflito e proponha opções em vez de sobrescrever cegamente.