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.
| Release Series | Latest Release | End of support | End of security fixes |
|---|---|---|---|
| 4.2 LTS | April 2023 | December 2023 | April 2026 |
| 4.1 | August 2022 | April 2023 | December 2023 |
| 4.0 | December 2021 | August 2023 | April 2023 |
| 3.2 LTS | 3.2.8 | December 2021 | April 2024 |
| 3.1 | 3.1.13 | April 2021 | December 2021 |
| 3.0 | 3.0.14 | August 2020 | April 2021 |
| 2.2 LTS | 2.2.20 | December 2019 | April 2022 |
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. We plan on upgrading troggle on the server whenever we upgrade the server operating system, which we do only every 2-3 years between Debian LTS releases.
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.
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). ]
Upgrading the version of django used by troggle is a serious programming job. It is not just a matter of editing a few config files. You will need a full troggle software development environment set up on your machine including, most definitely, the capability of running the troggle test suite. See how to set up a troggle software development laptop. Note particularly that you will find sqlite database browser software very helpful and that you will need to know git.
There are six critical tricks that make everything much, much easier:
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.
Even if you have made no changes to the data model, and thus the database scheme is unchanged, you still have to run the Django migration software between different Django Feature Releases, e.g. between 3.1.x and 3.2.y .
Even if you have not made any changes, Django itself may have made substantial changes to its admin data model and so the database structure needs to be migrated to the new structure - even though it is an empty database since we recreate it all every time we do a data import.
Now might also be a good idea to get familiar with using a database browser (see configuring a troggle laptop) and use it with the example project described in the Primer article: which you should run through on your own machine.
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 wheelThis 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$ 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.23To upgrade pip istelf, do $ pip install --upgrade pip
On the expo server we run MariaDB as the database which has its own dependencies. In particular
mysqlclient==1.3.10
This is only necessary if we hit a policy-imposed incomatibility, as we did with mysqlclient==1.3.10 . We have only ever had to do this once.
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