CUCC Expedition Handbook

Upgrading Django for Troggle

Why this is difficult

When django upgrades to a new version things break across the entire django package, including things which we don't conciously use but are internal dependencies within django. These were 'the way to do it' when troggle was first written for django 0.7 in 2006. So upgrading troggle to a new django version requires not just a broad beadth of knowledge across troggle, but also across the entire breadth of django itself. And the error messages are sometimes very unhelpful.

Django versions and update schedule

Release Series	Latest Release	End of support	End of security fixes
3.2 LTS	April 2021	December 2021	April 2024
3.1	3.1.7	April 2021	December 2021
3.0	3.0.13	August 2020	April 2021
2.2 LTS	2.2.20	December 2019	April 2022
1.11 LTS	1.11.29	December 2017	April 2020

Major, minor and releases

Django release 2.2.20 is major-version 2, minor-version 2, and patch-release 20. 2.2 is the "feature release" and patch releases within each feature release are not meant to break anything. They are just to fix bugs.

Things will break between feature releases which come out every 8 months.

You will come to rely extensively on the release notes and versions documentation which is maintained by django.

You will also need to read the django guide to upgrading to newer versions.

Django plugins ("apps")

Documentation for the plugins is highly variable and plugin projects, being run by volunteers, can just die unexpectedly. For the django-registration plugin there are two sources of current information:
Docs: django-registration 3.1
PyPi: django-registration 3.1

but only one of these (PyPi) gives release history data - which is what you need if you get behind with the django upgrades.

Django plugin documentation cannot be relied upon to tell you which version of django they require. They will complain when you run them if your version of django is too old though. Some experimentation is required.

[ However django-extensions looks like it could be useful explicitly to help us through the upgrade process: pypi.org/project/django-extensions/ (only available for django 2.2 and later). ]

Important Tricks

There are six critical tricks that make everything much, much easier:

Use pip venv or virtualenv to set up a virtual python environment within which you can easily and quickly change the specific releases of python, django, django's dependencies and django plugins. With a previously created venv py37d2 start it up like this:
cd py37d22 source bin/activate python --version cd troggle django-admin python manage.py python manage.py validate -v 3 --traceback django-admin check python manage.py test -v 3 --traceback
Use the highest release number when upgrading between minor-versions of django.
So we went from 1.8.19 to 1.9.13 to 1.10.8 to 1.11.29 to 2.0.13 to 2.1.15 then 2.2.19 (.20 was not released then) and next we will go to 3.2.x .
Use the django 'check' maintenance system at the most verbose setting at each release
troggle$ python manage.py check -v 3 --deploy
troggle$ python -Wall manage.py check
Use our test suite (and if you see errors, run it with -v 3)
troggle$ python manage.py test [-v 3]
Read all the release notes for all the intermediate releases. So from 1.1.29 we read 14 sets of notes: for 2.0, 2.0.1, 2.0.2... up to 2.0.13 .
Seriously learn how to use the traceback webpage produced by django when a page crashes. There is a full record of every variable value hidden in there.
You will be doing a lot of local testing just on your development machine. The default is to use the webserver built into Django: python manage.py runserver 0.0.0.0:8000 -v 3. Alternatively you can install and use gunicorn: gunicorn --reload -w 9 -b :8000 wsgi. the '-w' flag is for the number of worker threads and should be 2n+1 where n is the number of cpu cores on your machine.

Deprecation warnings and python versions

The individual releases within a minor version don't break anything but do fix bugs. So if you are on 1.10.x there is no point in getting 1.11.1 to work and you should go straight to 1.11.29 .

check --deploy gives django warnings about security issues in your settings as well as django deprecation warnings.
-Wall is a standard python option and gives warnings of deprecated python features used by django and all the current plugins. So it tells us that django 1.11.29 is using a deprecated python language feature which will be removed from the language in python 3.9 . Python version compatibilities are documented at the top of each x.0 release note. From Django 3.0 it requires python 3.6.

The upgrade process

ensure that you have the exact version of python installed on your machine as is live for troggle on the server, e.g. do $ sudo apt install python3.7.5.
create a venv using the version of python to be used.
do a clean install of django and troggle using pip.
check the versions of plugins using pip list -o
open two terminal windows:
- - one will be used for installations and tests.
- - the other one will be used for python manage.py runserver 0.0.0.0:8000 -v 3 (or whatever portnumber you like)
rename the most recent localsettingsXXX.py to fit your local system and copy it to localsettings.py
run a script to make a sanitised copy (no passwords) of localsettings.py as localsettingsXXX.py before every commit
edit your localsettings.py to use sqlite with a file troggle.sqlite
edit your localsettings.py to set a password for users "expo" & "expoadmin" (or just use default "nnn:gggggg")
testing:
- run troggle$ python manage.py test
- run the full data import troggle$ python databaseReset.py reset R000. It should take about 80 seconds to import everything.
- start the runserver in the other terminal window and open a web browser to http://localhost:8000 and check important pages which we don't have tests for (yet):
  - http://localhost:8000/pathsreport
  - http://localhost:8000/stats
  - http://localhost:8000/people
  - http://localhost:8000/expedition/2018
  - http://localhost:8000/expofiles/surveyscans/2019/walletindex.html
  - http://localhost:8000/survey_scans/
  - http://localhost:8000/survexfile/caves/
  - http://localhost:8000/dwgdata/
  - http://localhost:8000/expofiles/rigging_topos/264/entrance_topo_2016.pdf
  - http://localhost:8000/expofiles/rigging_topos/264/entrance_topo_2016.svg
  - http://localhost:8000/expofiles/rigging_topos/264/entrance_topo1_2016.jpeg
  - http://localhost:8000/expofiles/training-info/Idiots guide to accessing expo git.pptx
  - http://localhost:8000/1623/291/291.htm
  - http://localhost:8000/caves
  - ttp://localhost:8000/admin/doc/models/core.expedition/ (admin login required)
  - http://localhost:8000/survexfile/204
Use the error dump tracebacks to find and correct the python code. [Running the server in a debugger would help: please add those instructioons for that to this page.]
run the script ./pre-run.sh to clean up everything before the next round of tests.

Django dependencies

You can upgrade the version of python installed within pip venv but not downgrade. So get that first venv installed right.

Here is example of installed (Version) and most-recent-available (Latest) verisons of pip installations.

Package    Version Latest Type
---------- ------- ------ -----
Django     2.2.19  3.2    wheel
docutils   0.14    0.17   wheel

This only gives any output for packages which are not the most recent. To see what is actually installed use

$ pip freeze
confusable-homoglyphs==3.2.0
Django==2.2.19
docutils==0.17
Pillow==8.2.0
pytz==2021.1
sqlparse==0.4.1
Unidecode==1.2.0

Although the above all work fine, on debian buster we are actually using the standard installs which are older:

$ pip freeze
confusable-homoglyphs==3.2.0
Django==2.2.19
docutils==0.14
Pillow==5.4.1
pytz==2019.1
sqlparse==0.2.4
Unidecode==1.0.23

To upgrade pip istelf, do $ pip install --upgrade pip

Django database dependencies

On the expo server we run MariaDB as the database which has its own dependencies. In particular

mysqlclient==1.3.10

which is technically incompatible with Django 2.2 which requires 1.3.13. This incompatibility is a policy choice by the Django team. Wookey ran the Django system tests with this (April 2020) and it works fine.

To run Django's system test suite:

Follow the instructions in the "Unit tests" section installed locally at docs/internals/contributing/writing-code/unit-tests.txt, published online at docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/ This involves running git clone on the django source repo to download the tests. We hope we never have to do this again but in case we get incomprehensible bugs in future, we should be prepared to do so.

We should not need to anything until we move from django 2.2 LTS to 3.2 LTS which we may never do.

Current upgrade status is documented: here.

Go on to: Troggle architecture
Return to: Troggle intro
Troggle index: Index of all troggle documents