# Documentação Django 5.2.8

# How to upgrade Django to a newer version

Apesar de ser um processo complexo as vezes, atualizar a versão do Django tem muitos benefícios:

- Novas características e melhorias são adicionadas.

- Erros são ajustados.

- Versões anteriores do Django eventualmente não irão receber atualizações de segurança. (veja Versões suportadas).

- Atualizando assim que cada versão do Django fica disponível faz com que futuras atualizações sejam menos dolorosas, por mantendo sua base de código atualizada.

Tools to help with version upgrades

Django has a vibrant ecosystem. There are automated upgrade helpers highlighted on the Community Ecosystem page.

Aqui alguns pontos para considerar para ajudar fazer seu processo de atualização mais suave tanto quanto possível.

## Leitura requerida

Se esta é sua primeira vez fazendo uma atualização, é útil ler o guia sobre o processo de atualizações diferente.

Afterward, you should familiarize yourself with the changes that were made in the new Django version(s):

- Leia as notas sobre a edição para cara edição a partir da sua versão de Django corrente, até e inclusive a versão do Django pra qual que você planeja atualizar.

- Dê uma olhada no linha do tempo da depreciação para as versões relevantes.

Preste uma atenção particular a incompatibilidades das mudanças nas versões anteriores para ter uma idéia clara do que será necessário para uma atualização de sucesso.

If you’re upgrading through more than one feature version (e.g. 2.0 to 2.2), it’s usually easier to upgrade through each feature release incrementally (2.0 to 2.1 to 2.2) rather than to make all the changes for each feature release at once. For each feature release, use the latest patch release (e.g. for 2.1, use 2.1.15).

A mesma abordagem de atualização incremental é recomendada quando for atualizar de um lançamento LTS para outro.

## Dependências

Na maioria dos casos para atualizar para a última versão do Django será necessário atualizar as dependências do Django também. Se a versão do Django foi lançada recentemente ou se algumas de suas dependências não são muito bem mantidas, algumas dependências podem não dar suporte a versão do Django. Nestes casos você terá que esperar até que a nova versão das dependências sejam lançadas.

## Resolvendo alertas de descontinuidade

Antes de atualizar, é uma boa idéia resolver qualquer alerta de descontinuidade emitido pelo projeto enquanto estiver usando sua versão do Django atual. Resolvendo estes alertas antes da atualização assegure-se que você tenha informações de todas as áreas do código que precisam de alteração.

Em Python, avisos de código obsoleto são silenciados por padrão. Você deve ativá-los usando a opção de linha de comando Python `-Wa`, ou então a variável de ambiente `PYTHONWARNINGS`. Por exemplo, para exibir alerta durante a execução de testes:

/ 

    $ python -Wa manage.py test

    ...\> py -Wa manage.py test

If you’re not using the Django test runner, you may need to also ensure that any console output is not captured which would hide deprecation warnings. For example, if you use pytest:

    $ PYTHONWARNINGS=always pytest tests --capture=no

Resolva qualquer alerta de descontinuidade com sua versão atual do Django antes de continuar o processo de atualização.

Aplicações de terceiros talvez usem APIs obsoletas para suporta múltiplas versões do Django, então alertas de descontinuidade em pacotes que você tenha instalado não indicam necessariamente um problema. Se um pacote não dá suporte a última versão do Django, considere enviar uma “issue” ou um “pull request” para ele.

## Instalação

Once you’re ready, it is time to install the new Django version. If you are using a `virtual environment` and it is a major upgrade, you might want to set up a new environment with all the dependencies first.

Se você tiver instalado Django com pip, você pode usar a flag `--upgrade` ou `-U`.

/ 

    $ python -m pip install -U Django

    ...\> py -m pip install -U Django

## Testando

Quando o novo ambiente estiver definido, rode todo pacote de teste para sua aplicação. De novo, é útil ligar os alertas de descontinuidade de modo que sejam mostrados na saída dos testes (você também pode usar a “flag” se testar sua aplicação manualmente usando `manage.py runserver`):

/ 

    $ python -Wa manage.py test

    ...\> py -Wa manage.py test

Depois que rodar os testes, concerte as falhas. Enquanto você tem as notas da versão frescas na sua cabeça, talvez seja uma boa hora para tirar vantagem das novas características do Django refatorando o código para eliminar qualquer alerta de descontinuidade.

## Deploy

Quando você estiver suficientemente confiante que sua aplicação funciona com a nova versão do Django, você está pronto para ir em frente e implantar seu projeto com Django atualizado.

Se você estiver usando o cache fornecido pelo Django, você deve considerar limpar o cache depois da atualização. De outro modo você pode ter problemas, por exemplo, se você estiver mantendo em cache objetos serializados e estes objetos não tem garantia de compatibilidade de serialização entre as versões do Django. Um problema de incompatibilidade no passado foi o cache de objetos `HttpResponse` serializados, diretamente ou indiretamente via o decorador `cache_page()`.