Upgrading a Windows Server 4.0.0 installation to 4.0.1
4.0.1 is a patch release containing no database migrations. On Windows Server the upgrade is a code update, a dependency sync and a restart:
Stop the scheduled task and the web service
git fetchandgit pulluv sync --exact --extra win --extra mssql, then activate.venvpython manage.py checkpython manage.py migrateandpython manage.py collectstaticStart the service and scheduled task again
You never name a version. The installation guide checks out the releases/4.0
branch rather than a version tag, so the branch carries each patch as it is released
and a git pull is all that moves you between them.
These steps apply to any 4.0.x patch, not only this one. What changes between patches is in the next section.
Note
The service and scheduled task names stopped carrying version numbers in 4.0.0 precisely so that patch upgrades would not require renaming anything. If you upgraded to 4.0.0 from v3.x, your service is called QATrack+ Web Service and your scheduled task QATrack+ Django Q Cluster.
Before you start
Back up your database, your qatrack/media folder and your local_settings.py,
as you would for any upgrade.
Finish or discard any QC session you have part-way through, before you upgrade. An autosaved session that straddles an upgrade is not guaranteed to come back exactly as you left it, and QATrack+ does not promise that it will.
Why, and what it means for you
An autosave holds the values a person had typed but not yet submitted. Dates among them are stored as the text that was on screen, in whatever format the site displayed at the time, so a release that changes how dates are displayed changes how that text has to be read.
4.0.2 does convert them where it can: an autosave written in the format earlier 4.0.x releases displayed is re-read and converted on load. Where a value cannot be read in any format the site now accepts, the field comes up empty and has to be typed again - which is deliberate, because an empty field can be seen and corrected while a plausible wrong date cannot.
Nothing already submitted is affected. Saved QC sessions, test list instances, service events and faults are stored as dates, not as text, and no upgrade changes them. This is only about sessions nobody has finished.
This is not something the project plans to guarantee. Making in-flight
autosaves survive every upgrade would mean versioning the autosave payload and
migrating it, for data that is transient by design - it is discarded after
AUTOSAVE_DAYS_TO_KEEP days, 30 by default. The effort is better spent
elsewhere, and the practical answer is the one at the top of this note: submit or
abandon what is in progress before upgrading.
Check that your existing backups contain a database
Before this release manage.py backup_site skipped the database on MySQL -
and on any engine it does not implement - while still reporting success. A backup
set could therefore hold media and settings and no database at all.
Look inside your most recent backup before relying on it. For MySQL, use
mysqldump.
From 4.0.1 the command names the engine it cannot handle rather than passing silently - but it still exits zero, so anything scheduled around its exit status cannot tell the difference. Check the output, or check that a database file is there.
It writes a database backup on SQL Server and SQLite only. PostgreSQL is not
one of them: the command has always reported that it cannot, so if your
PostgreSQL site has been relying on it, check now. Use pg_dump, or the
Docker backup script, which does.
What needs your attention in this release
Most of 4.0.1 is bug fixes that need nothing from you. These four do:
Python 3.12 and Django 4.2.30 or newer are now required. The Django floor was
raised for its security fixes and Python is pinned to 3.12. uv sync below
installs the right versions; you do not need to change anything by hand.
If you deploy with Docker, check your backup environment variables. The backup
script now reads POSTGRES_DB, POSTGRES_USER and POSTGRES_PASSWORD from
the environment instead of having the database name and user written into it. These
are the same variables the postgres service already uses, so a deployment that
sets them in its .env needs no change. One that had customised the hard-coded
values was previously dumping the wrong database, or nothing — confirm your next
backup contains what you expect.
If you deploy with Docker, you may now set CSRF_TRUSTED_ORIGINS from the
environment. It falls back to ALLOWED_HOSTS when not given. See the comments in
deploy/docker/.env.example.
The installfixtures management command has been removed. It loaded a
fixture set that no longer matched the schema. If you called it from a script, use
manage.py loaddata with the fixtures you want instead.
Changes to local_settings.py
Nothing in this release requires a change to local_settings.py. Your existing
file keeps working. There is one thing to check and two new settings you may want.
Remove LOGIN_EXEMPT_URLS if your local_settings.py sets it
Warning
This is the one item on this page with a security consequence. Setting
LOGIN_EXEMPT_URLS replaces the shipped list rather than adding to it, so your
copy overrides the corrected one and keeps whatever fault it was copied with.
If the setting appears in your local_settings.py , delete the whole
assignment unless you deliberately need entries of your own. The shipped default is
correct as of 4.0.1, and removing your copy means you also receive any future
correction.
Two older values are worth recognising, because both are worse than the current default:
# the commented example the installation templates carried from 2018
LOGIN_EXEMPT_URLS = [r"^qatrack/accounts/", r"qatrack/api/*"]
# the shipped default before 4.0.1
LOGIN_EXEMPT_URLS = [r"^favicon.ico$", r"^accounts/", r"api/*", r"^oauth2/*", r"^i18n/"]
These are regular expressions, not globs. api/* reads as api followed by zero
or more slashes, so it also exempts apifoo, api_secret and anything else merely
beginning with those three letters. ^favicon.ico$ leaves the . unescaped, matching
any character. The 2018 example additionally carries a qatrack/ prefix that no longer
matches anything, and omits four entries the current default has — so a site using it
requires a login for its favicon, OAuth2 and both translation catalogues.
If you do need your own entries, add them to a copy of the current default rather than an older one:
LOGIN_EXEMPT_URLS = [
r"^favicon\.ico$",
r"^accounts/",
r"^api(/|$)",
r"^oauth2(/|$)",
r"^i18n/",
r"^jsi18n/",
# your own entries here
]
See Configuring a QATrack+ Installation for the full explanation.
Two new settings, both optional
LANGUAGE_COOKIE_AGE sets how long a user’s language choice is remembered. It
now defaults to one year; before this release the cookie had no explicit lifetime, so
it expired with the browser session and the interface reverted to the default language
on the next visit. To shorten it:
LANGUAGE_COOKIE_AGE = 30 * 24 * 60 * 60 # 30 days
CSRF_TRUSTED_ORIGINS may now be set from the environment, which is mainly of
interest to Docker deployments. When the CSRF_TRUSTED_ORIGINS environment variable
is set it is read as a comma-separated list; when it is not, it is derived from
ALLOWED_HOSTS. You can still set it directly in local_settings.py if you prefer.
See the comments in deploy/docker/.env.example.
Running the upgrade
Stop the scheduled task and the web service:
>> Stop-ScheduledTask -TaskName "QATrack+ Django Q Cluster"
>> Stop-Service "QATrack+ Web Service"
Fetch the new version and update the environment. You do not name a version — the
releases/4.0 branch you installed from carries the patch:
>> cd C:\deploy\qatrackplus
>> git fetch origin
>> git pull
>> uv sync --exact --extra win --extra mssql
Activate the environment. uv sync updates .venv but does not activate it,
and the commands below are run with the environment’s own python:
>> .\.venv\Scripts\Activate.ps1
Your command prompt should now be prefixed with (qatrackplus) or (.venv).
Without this, in a fresh PowerShell window python is the system interpreter -
or Windows’ Python Store alias, which opens the Microsoft Store instead of running
anything - so the commands below would either fail on missing dependencies or
run against the wrong environment, while your services are stopped.
Check the installation, then run the migration step and collect static files:
>> python manage.py check
>> python manage.py migrate
>> python manage.py collectstatic
Restart:
>> Start-Service "QATrack+ Web Service"
>> Start-ScheduledTask -TaskName "QATrack+ Django Q Cluster"
After upgrading
Check your group permissions, once, if any group was created in v3.x. Under Authentication and Authorization → Groups, confirm that wherever a group has Can change X it also has Can view X.
Why those groups are missing it
Django added a separate view permission per model in version 2.1, so groups set
up before that have change without it. The admin hides this, because Django
treats change as implying view — but some admin widgets check for view
alone, and refuse the request that fills the field in.
What this will not fix
If a Test List’s memberships show a test’s ID and macro name but no test name, group permissions are not the cause and granting them will change nothing. That is a separate fault, reported as #897 and present in every 4.0 release up to and including this one: the admin answers the request that fetches the name with a 404 before any permission is considered, so it fails for every user including a superuser. A fix is in hand for a later release.
The permission check above is still worth doing - it is a real cause of a blank field in other places, and it costs one look at your groups - but do not expect it to restore a missing test name.
Confirm your backups — if you act on one thing in this release, make it the backup check at the top of this page. It applies to MySQL and to PostgreSQL, for different reasons.