This document describes aspects of the system which should be given particular attention when upgrading Wagtail or its dependencies.
We are maintaining our own forks of Wagtail packages at: https://github.com/torchbox-forks.
The enables any team member to propose a change to a package, we can all work directly on the work branch and submit it to the original author for consideration.
As much as possible, we want to use the official releases available on PyPI for the Wagtail package dependencies. A temporary solution is to fork the package dependency, tag the working branch, and use the tag in the pyproject file.
Last tested for wagtail 6.0 upgrade Comments in the pyproject.toml file may have more detailed information.
It is important to replace the usage of the git tags in the pyproject.toml file with the official release version from PyPI as soon as they become available.
The following areas of functionality are critical paths for the site which don’t have full automated tests and should be checked manually.
App https://github.com/torchbox/rca-wagtail-2019/tree/master/rca/account_management
The account management app provides the functionality for administrators to create student accounts. Most of this IS covered by unit tests, however it’s still worth doing a test over the UI.
admin/student/create, fill in the details and assign the collection, make sure ‘create student page’ is true.Expected behaviour after submitting the form:
App https://github.com/torchbox/rca-wagtail-2019/tree/master/rca/people
Most of the custom logic for students is covered by tests, but again it’s worth testing the UI for any changes between wagtail versions.
Given in 1 (above) a student account is created, the student is able to sign in and edit their own page. There are a number of fields that we don’t want the student to be able to edit. E.G title, collection, page link. There are also fields that we don’t want anyone to be able to edit.
How to test:
URL: https://www.rca.ac.uk/register-your-interest/ App: https://github.com/torchbox/rca-wagtail-2019/tree/master/rca/enquire_to_study
Whilst there are unit tests for this form, it has 2 integrations so important to test this form.
When submitted the form will geneate a submission object at admin/enquire_to_study/enquiryformsubmission/.
How to test:
URL: https://www.rca.ac.uk/study/application-process/funding-your-studies/rca-scholarships-and-awards/express-interest/ App: https://github.com/torchbox/rca-wagtail-2019/tree/master/rca/scholarships
Scholarships are added as snippets admin/snippets/scholarships/scholarship/ and are rendered as choices on the form. After submitting the form, a submission object should be created in the admin at admin/scholarships/scholarshipenquiryformsubmission/
How to test:
admin/scholarships/scholarshipenquiryformsubmission/The RCA intranet supports importing certain page types to the intranet from the main site. This is done by reading the pages API endpoint. Testing this can be a little tricky, but rca-inforca-staging can be used to test it, as that staging site has the env var RCA_CONTENT_API_URL to read from the rca-develompoent site.
How to test:
As well as testing the critical paths, these areas of functionality should be checked:
rca.utils.pipeline.make_sso_users_editors and added to the SOCIAL_AUTH_PIPELINE. RCA will manually elevate permissiosn if necessary./admin/logout/ endpoint to redirect users who logged in to /logout/. This is a confirmation screen that users will still need to manually log out of their SSO accounts. This is done with rca.account_management.views.CustomLogoutView and rca.account_management.views.SSOLogoutConfirmationView.The following templates are overridden and should be checked for changes when upgrading Wagtail:
Last checked against Wagtail version: 6.1
rca/account_management/templates/wagtailadmin/base.htmlrca/project_styleguide/templates/patterns/pages/auth/login.html - This was overridden to add the “Sign in with single sign-on” button to the login template.rca/users/templates/wagtailusers/users/list.htmluser_listing_buttons template tag was used in this template, and it has since been deprecated.!!! warning “Technical Debt - to be addressed in Wagtail 6.2”
The deleted `rca/users/templates/wagtailusers/users/list.html` template did two things:
1. altered the "Admin" (now called "Access level") column to show "Yes" if `user.is_superuser`.
The default behaviour is to show "Admin" if `user.is_superuser`.
2. added a "Groups" column after the preceding column, whose contents are ``
Retaining the above functionality in Wagtail 6.1 is not a trivial task.
There's currently an [open PR](https://github.com/wagtail/wagtail/pull/11952) which
seeks to solve this problem, and it may be ready in the 6.2 release.
**Action**: When upgrading to Wagtail 6.2, look out for the above change, and restore
the feature to the way it was before the 6.1 upgrade.
This is the path to the Django template which is used to display the “password required” form when a user accesses a private page. For more details, see Wagtail’s Private pages documentation.
WAGTAIL_PASSWORD_REQUIRED_TEMPLATE = "patterns/pages/wagtail/password_required.html"
We don’t generally upgrade python versions until a new LTS/Major version is released and has been stable for a while. We prefer to be running a more stable version of python.
If you are upgrading python, you should check the following python version references are updated:
python key in the tool.poetry.dependencies section of the pyproject.toml file.python key in the pre-commit configuration file .pre-commit-config.yaml.python image tag in the Dockerfile/s.gitlab-ci.yaml.If you are upgrading python. There is a development tool available to help with modernising the codebase. This is installed as part of the poetry development dependencies.
To run the tool, use the following command:
git ls-files -z -- '*.py' | xargs -0 pyupgrade [python-version-arg]
Where [python-version-arg] is the version of python you are upgrading to.
To view the available version arguments, use the following command:
pyupgrade --help
The pyupgrade tool is run as a step in the pre-commit configuration. This will help you to use the modern syntax as you work on the codebase.
You can manually run the pre-commit checks on *.py files using the following command:
git ls-files -z -- '*.py' | xargs -0 | pre-commit run --files
If you are upgrading Django. There is a development tool available to help with modernising the codebase. This is installed as part of the poetry development dependencies.
If you are upgrading django. There is a development tool available to help with modernising the codebase. This is installed as part of the poetry development dependencies.
To run the tool, use the following command:
git ls-files -z -- '*.py' | xargs -0 django-upgrade --target-version [django-version-arg]
Where [django-version-arg] is the version of Django you are upgrading to.
The django-upgrade tool is run as a step in the pre-commit configuration. This will help you to use the modern syntax as you work on the codebase.
You can manually run the pre-commit checks on *.py files using the following command:
git ls-files -z -- '*.py' | xargs -0 | pre-commit run --files