<p>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.
<p>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:<br/>
<p>but only one of these (PyPi) gives release history data - which is what you need if you get behind with the django upgrades.
<p>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.
<p>[ However django-extensions looks like it could be useful explicitly to help us through the upgrade process:
<ahref="https://pypi.org/project/django-extensions/">pypi.org/project/django-extensions/</a> (only available for django 2.2 and later). ]
<li>Use <ahref="https://docs.python.org/3/library/venv.html">pip venv</a> 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.
<var><ahref="https://docs.gunicorn.org/en/stable/design.html">gunicorn</a> --reload -w 9 -b :8000 wsgi</var>. 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.
<p>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 .
<p>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.
<ul>
<li><ahref="https://docs.djangoproject.com/en/3.2/topics/migrations/">Django migrations documentation</a>. Read it all even if you don't understand it all yet. You will come back to it.
<li><ahref="https://realpython.com/django-migrations-a-primer/">Django Migrations: A Primer</a>. A training course in migrations. Really useful.
<li><ahref="https://docs.djangoproject.com/en/3.2/ref/django-admin/#django-admin-makemigrations">command line documentation</a> for the 'makemigrations' and 'migrate' commands.
<p>Now might also be a good idea to get familiar with using a database browser (see <ahref="troglaptop.html#dbtools">configuring a troggle laptop</a>) and use it with the example project described in the Primer article: which you should run through on your own machine.
<h4>Running troggle before and after a Django migration</h4>
<li>ensure that you have the exact version of python installed on your machine as is live for troggle on the server, e.g. do <var>$ sudo apt install python3.7.5</var>.
<li>create a venv using the version of python to be used. <br>We have a script to help you do this in <var>:troggle:venv-trog.sh</var> (but it is fragile and often broken)
<li>run the full data import <var>troggle$ python databaseReset.py reset R000</var>. It should take about 5 minutes to import everything (11 minutes on a slow core 2 duo laptop). ("R000" is just a label, use whatever you like.)
<li>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). These are listed in <ahref="troglaptop.html">the troggle laptop installation instuctions</a>.
<li>Use the error dump tracebacks to find and correct the python code. [Running the server in a debugger would help: please add those instructions for that to this page.]
Follow the instructions in the "Unit tests" section installed locally at docs/internals/contributing/writing-code/unit-tests.txt, published online at <ahref="https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/#running-the-unit-tests">docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/</a>
This involves running <var>git clone</var> 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.
