Django 3.2 Upgrade: Steps to Upgrade a Repository

Created by Jeremy Bowman
Last updated: Jul 28, 2021 by Usama Sadiq

We want to make sure our code works with Django 3.2 (the newest LTS release) before support ends for Django 2.2 in April 2022 (and ideally by mid-Oct. For each Django-using library and service, we recommend doing the following steps. These may be split into more than one PR; try to avoid changing more than about 20 files in one PR if practical (for ease of review). edX employees upgrading an IDA should update the IDA's entry in the table on https://openedx.atlassian.net/wiki/spaces/AC/pages/2866086194 when each chunk of the upgrade is completed.

  1. Remove any versions of Python earlier than 3.8 from tox.ini, .travis.yml, and GitHub Actions workflows (there are scripts in https://github.com/edx/repo-tools/tree/master/edx_repo_tools/codemods/django3 that can do this automatically in most cases)

  2. If the repository is still using Travis CI, switch it to use GitHub Actions instead as outlined in https://openedx.atlassian.net/wiki/spaces/SRE/pages/2038792440 (if you don’t have access to that page, try https://docs.github.com/en/actions/learn-github-actions/migrating-from-travis-ci-to-github-actions). Travis CI minutes now generally cost money even for open source projects (among other problems), so we shouldn’t add new test configurations to that service.

  3. Upgrade any packages that were being held back only because of missing support for one of the removed Python versions

  4. Install pyupgrade-directories package and run pyup-dirs --py3-plus --py36-plus --py38-plus --recursive . in the repo root folder to clean up code that was only present to support older Python versions. You may want to run each of the --py* options in a separate PR if they make a lot of changes.

  5. Run the codemod scripts in https://github.com/edx/repo-tools/tree/master/edx_repo_tools/codemods/django3 (such as replace_unicode_with_str.py and script_to_replace_static.sh) to automatically fix some code patterns known to break under Django 3.2.

  6. Fix any deprecation warnings related to Django 3.0 or 3.1 that occur when the tests are run with Django 2.2

  7. Add test configurations for Django 3.0, 3.1, and 3.2 to both tox.ini and the GitHub Actions CI workflow. (The scripts in https://github.com/edx/repo-tools/tree/master/edx_repo_tools/codemods/django3 can usually handle this.) If any of them fail, update the configuration to allow them to do so for now so the failures can be addressed in later PRs.

  8. Fix any remaining Django deprecation warnings or test failures in all the test configurations. But don’t fix deprecation warnings from the Django 3.2 tests yet, fixes for them are likely to break compatibility with Django 2.2 which we still need for now.

  9. If any of the new test configurations were allowed to fail when added, update the configuration to no longer allow them to do so.

  10. Update the Trove classifiers in any setup.py, setup.cfg, or pyproject.toml files to reflect the Python and Django versions currently being tested

  11. For packages already on PyPI, go ahead and make a new release so the Trove classifiers are updated there also. This should be a major version bump if support for older Python releases was dropped.

  12. If the repository is an IDA, go ahead and update it to deploy on Django 3.2 once all of the new test configurations are passing cleanly.