upgrade-django

Upgrade Django

When to use

• The user asks to upgrade Django, or the project is below 5.2 (see legacy/django-legacy).
• A security fix exists only in a supported release (5.2, 6.0, 6.1).
• Moving from 5.2 LTS to 6.x as a planned change.

For a patch release within the same feature release, update the pin and run Verify.

Before you start

• Read django, Python, and every Django add-on with its supported Django range: djangorestframework (3.17 supports 4.2–6.0; 3.18 needs 5.2+), django-cors-headers, django-filter, celery/django-celery-*, django-allauth, django-storages, channels, admin themes, and anything with its own migrations.
• Python compatibility per target: 5.2 supports 3.10–3.14; 6.0 and 6.1 need 3.12+. Plan upgrade-python first if needed.
• Working tree clean; new branch (chore/django-5.2).
• Ask the user:
  • the target (default: 5.2 LTS, security support to Apr 2028; 6.1 if they want the newest and can take Python 3.12+);
  • whether to stop after each feature release for review;
  • whether network installs are approved (core/supply-chain cooldown applies).
• Plan the hops: each feature release in turn (4.2 → 5.0 → 5.1 → 5.2 → 6.0 → 6.1). From older versions, go LTS to LTS through every intermediate release (2.2 → 3.0 → 3.1 → 3.2 → 4.0 → 4.1 → 4.2), fixing warnings at each step.

Steps

1. Baseline: locked install, python manage.py check, tests, makemigrations --check. Record failures.

2. Patch the current release to its last patch (for example 4.2.30) and run the tests with warnings visible:

   python -Wd manage.py test                 # or: python -W error::DeprecationWarning -m pytest
   

   Fix every RemovedInDjangoXXWarning for the next release now; that's what breaks on the hop.

3. Hop one feature release:

   • pin django~=5.0.0 (the next release), upgrade add-ons to versions that support it, re-lock and sync;
   • run django-upgrade with the new target and review the diff: