# Documentation Django 3.1.9.dev

# Mise à jour de Django à une version plus récente

Même si le processus peut être parfois un peu complexe, la mise à jour de Django à sa dernière version présente plusieurs avantages :

- De nouvelles fonctionnalités et améliorations ont été ajoutées.
- Des bogues ont été corrigés.
- Les versions plus anciennes de Django ne reçoivent plus de mises à jour de sécurité après un certain temps (voir Versions prises en charge).
- En mettant à jour Django lors de chaque nouvelle publication, vous vous facilitez le travail sur les mises à jour suivantes car votre code reste toujours à jour.

Voici quelques éléments à considérer pour rendre le processus de migration aussi agréable que possible.

## Lecture conseillée

S’il s’agit de votre première mise à jour, il est utile de lire le guide sur les différents processus de publication.

Après cela, nous vous suggérons de vous familiariser avec les modifications qui ont été apportées dans la nouvelle version de Django :

- Lisez les notes de publication de chaque version « finale » suivant votre version actuelle de Django, jusqu’à la version vers laquelle vous pensez effectuer la mise à jour.
- Examinez la planification d’obsolescence pour les versions concernées.

Prêtez une attention particulière aux modifications non rétrocompatibles pour avoir une bonne vision de ce qui sera nécessaire pour une mise à jour réussie.

Si vous mettez à jour en sautant plus d’une version majeure (par ex. 2.0 vers 2.2), il est généralement plus simple de mettre à jour en passant par chaque version majeure intermédiaire (2.0 vers 2.1, puis vers 2.2) plutôt que d’effectuer d’un coup tous les changements nécessaire pour toutes les versions majeures. Pour chacune des versions intermédiaires, utilisez la dernière publication corrective (par ex. pour 2.1, utilisez 2.1.15).

La même approche de mise à jour incrémentale est recommandée lors de la mise à jour d’une version LTS vers la suivante.

## Dépendances

Dans la plupart des cas, il sera aussi nécessaire de mettre à jour à la dernière version des dépendances Django. Si la version de Django a été publiée récemment ou si certaines de vos dépendances ne sont pas bien maintenues, il est possible que certaines dépendances ne prennent pas encore en charge la nouvelle version de Django. Dans ce cas, il se peut que vous deviez patienter jusqu’à ce que de nouvelles versions de vos dépendances aient été publiées.

## Résolution des avertissements d’obsolescence

Avant de mettre à niveau, il est recommandé de résoudre les avertissements d’obsolescence générés par votre projet avec la version actuelle de Django. La correction de ces avertissements avant la mise à niveau garantit que vous soyez informés au sujet des bouts de code qui ont besoin d’être modifiés.

En Python, les avertissements d’obsolescence sont silencieux par défaut. Vous devez les activer par l’option de ligne de commande Python `-Wa` ou avec la variable d’environnement `PYTHONWARNINGS`. Par exemple, pour afficher les avertissements lors du lancement des tests :

/ 

    $ python -Wa manage.py test

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

Si vous n’utilisez pas l’exécuteur de tests de Django, il se peut que vous deviez aussi contrôler que la sortie console n’est pas capturée, ce qui masquerait les avertissements d’obsolescence. Par exemple, si vous utilisez pytest:

    $ PYTHONWARNINGS=always pytest tests --capture=no

Résolvez tout avertissement d’obsolescence avec votre version actuelle de Django avant de continuer le processus de mise à niveau.

Les applications tierces peuvent utiliser des API obsolètes dans le but de prendre en charge plusieurs versions de Django. Des avertissements provenant de ces paquets installés ne signifient pas toujours qu’il y a un vrai problème. Si un paquet ne prend pas en charge la dernière version de Django, prenez le temps de créer un rapport d’anomalie ou d’envoyer un correctif pour ce problème.

## Installation

Quand vous êtes prêt, c’est le moment d”installer la nouvelle version de Django. Si vous utilisez un `environnement virtuel` et qu’il s’agit d’une mise à jour majeure, il peut être souhaitable de créer d’abord un nouvel environnement contenant toutes les dépendances.

Si vous avez installé Django avec pip, vous pouvez indiquer l’option `--upgrade` ou `-U`:

/ 

    $ python -m pip install -U Django

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

## Tests

Lorsque le nouvel environnement est installé, lancez la suite de tests complète de votre application. Encore une fois, il est utile d’activer ces avertissements d’obsolescence pour qu’ils apparaissent dans les résultats des tests (vous pouvez aussi utiliser le drapeau si vous testez votre application manuellement avec `manage.py runserver`) :

/ 

    $ python -Wa manage.py test

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

Après avoir exécuté les tests, corrigez les éventuelles erreurs. Un conseil : profitez du fait que les notes de publication sont encore fraîches dans votre mémoire pour mettre à jour votre code en tirant avantage des nouvelles fonctionnalités de Django et en éliminant ainsi d’éventuels avertissements d’obsolescence.

## Déploiement

Si vous êtes suffisamment confiant dans le bon fonctionnement de votre application avec la nouvelle version de Django, vous êtes prêt à aller de l’avant et à déployer votre projet Django mis à jour.

Si vous utilisez de la mémoire tampon (cache) fournie par Django, il est conseillé de vider cette mémoire après la mise à jour. Sinon, des problèmes peuvent apparaître. Par exemple, si des objets bruts (« pickled ») sont en mémoire tampon, il n’est pas garanti que ces objets puissent être reconstruits, car ce format brut n’est pas toujours compatible d’une version de Django à une autre. Un problème d’incompatibilité connu du passé concernait les objets bruts `HttpResponse` en mémoire tampon, directement ou indirectement via le décorateur `cache_page()`.