### Navigating the Transition to Wagtail 2.11 LTS
Jumping from one LTS (Long-Term Support) version to another in Wagtail can streamline the upgrade process, assuming no major roadblocks appear. As we approach Wagtail 2.11, it's important to prepare for more significant version jumps, which come with their own set of challenges and changes.
### Preparation Steps ๐
Before diving into the upgrade, start with these essential steps:
1. **Check Compatibility:** Review the [upgrading guide](https://docs.wagtail.org/en/stable/releases/upgrading.html) to ensure your current setups of Django and Python are compatible. Wagtail 2.11 supports Django versions 2.2 through 3.1 and Python 3.6 to 3.8. If youโre running Django 2.2 and Python 3.7 like I am, youโre all set. Otherwise, consider updating these as well.
2. **Review Major Changes:** Skim through the release notes for each major version you're skipping. Focus on Wagtail versions like 2.8, 2.9, and 2.10 to understand the significant changes. For instance:
- Wagtail 2.8 highlights the end of support for Django 2.0, prompting an upgrade to at least Django 2.2.
- Wagtail 2.9 and 2.10 continue this trend by dropping support for older Django and Python versions.
### Handling Deprecated Features and Migrations
One of the key changes in Wagtail 2.11 is the adjustment in middleware handling. Update your settings to accommodate these changes:
```python
MIDDLEWARE = (
...
# "wagtail.core.middleware.SiteMiddleware", # Remove this
"wagtail.contrib.legacy.sitemiddleware.SiteMiddleware", # Add this
# 'wagtail.contrib.redirects.middleware.RedirectMiddleware', # Remove this
'wagtail.contrib.redirects.middleware.RedirectMiddleware', # Add this
...
)
```
In Wagtail 2.9 `send_mail` was moved. If you're using the `send_mail` then consider this pathing update:
```python
from wagtail.admin.utils import send_mail
```
๐ From this ๐
๐ To this ๐
```python
from wagtail.admin.mail import send_mail
```
### Streamlining Dependencies ๐งน
As Wagtail evolves, it takes over the management of several dependencies that you might have pinned in your project. With Wagtail 2.11, it's a good time to clean up your `requirements.txt` to remove unnecessary dependencies that Wagtail now handles, such as `beautifulsoup4`, `Willow`, and others. Hereโs a quick way to clean up:
```bash
pip uninstall Willow beautifulsoup4 django-modelcluster django-permissionedforms django-taggit django-treebeard djangorestframework django-filter draftjs_exporter Pillow beautifulsoup4 Willow[heif] requests l18n openpyxl anyascii telepath laces
pip freeze > requirements.txt
```
### Upgrading Wagtail's v2 API
If you're using Wagtail's v2 API, make sure to update your API paths and imports to reflect the new structures introduced in Wagtail 2.11. The old `api.py` file, if you're using the Wagtail v2 API, would look something like this:
```python
# This is the old api.py file
from wagtail.api.v2.router import WagtailAPIRouter
from wagtail.images.api.v2.endpoints import ImagesAPIEndpoint
from wagtail.documents.api.v2.endpoints import DocumentsAPIEndpoint
api_router = WagtailAPIRouter('wagtailapi')
api_router.register_endpoint('pages', PagesAPIEndpoint)
api_router.register_endpoint('images', ImagesAPIEndpoint)
api_router.register_endpoint('documents', DocumentsAPIEndpoint)
```
If this is applicable to you, you'll want to replace the above โ๏ธ with the code below ๐
```python
from wagtail.api.v2.views import PagesAPIViewSet
from wagtail.api.v2.router import WagtailAPIRouter
from wagtail.images.api.v2.views import ImagesAPIViewSet
from wagtail.documents.api.v2.views import DocumentsAPIViewSet
api_router = WagtailAPIRouter('wagtailapi')
api_router.register_endpoint('pages', PagesAPIViewSet)
api_router.register_endpoint('images', ImagesAPIViewSet)
api_router.register_endpoint('documents', DocumentsAPIViewSet)
```
### Django 3.0+ considerations
By default Wagtail 2.11 will download Django 3.1.14. With this comes a few early upgrade considerations. If you've purposely stayed on Django 2.2, please disregard this until later.
* You may have problem with `django.utils.six`. If you absolutely need this package (most people don't need it), you can install the `six` package from PyPi. [https://pypi.org/project/six/](https://pypi.org/project/six/)
* `static` was changed modules.
```
# Change
from django.contrib.staticfiles.templatetags.staticfiles import static
# To
from django.templatetags.static import static
```
`NullBooleanField` is deprecated and will be removed in Django 4.0. We might as well replace that now with. [More info on that in the Django Docs](https://docs.djangoproject.com/en/3.1/ref/models/fields/#nullbooleanfield)
### Final Steps and Migration
After making all necessary adjustments, run:
```bash
python manage.py migrate
```
This command integrates all database changes. If you encounter any unusual errors, consider checking if a newer point release of Wagtail or Django addresses these issues.
## Packages to consider
#### django-allauth
If you're using this package while upgrading to Wagtail 2.11, try using:
```txt
django-allauth==0.45.0
```
### django-money
If you're using the `MoneyField` you have two options:
1. Upgrade `django-money==1.1` — this version works well with Wagtail 2.11 and Django 3.1, or
2. Replace `MoneyField` with `django.db.DecimalField`. [See the GitHub code here](https://github.com/django-money/django-money/blob/1.1/djmoney/models/fields.py#L161)
If you use `django-money==1.1` also make sure you version lock `py-moneyed==0.8` for the time being as newer versions don't support `django-money v1.1`
### django-adminactions
If you're using this package, `django-adminactions==2.0` seems to work decently.
Personally, I like to remove this package entirely in favour of Wagtail-based admin interactions.
### dj-stripe
Upgrading `dj-stripe` is a royal pain in the backside. Upgrade this package one step at a time -- there is zero skipping over versions.
> -------------------
> **Warning**: Avoid this package if you enjoy your sanity as a developer.
> -------------------
```
pip install dj-stripe==2.1
python manage.py migrate
pip install dj-stripe==2.2.*
python manage.py migrate
pip install dj-stripe==2.3
```
At `dj-stripe==2.3` you _will_ need to change your migration files. Do a global find-and-replace:
**Find:**
```
('djstripe', '0003_auto_20181117_2328_squashed_0004_auto_20190227_2114')
```
**Replace with:**
```
('djstripe', '0001_initial'),
```
Now we can upgrade again making our way to `dj-stripe==2.5`
```
python manage.py migrate
pip install dj-stripe==2.4
python manage.py migrate
pip install dj-stripe==2.5
```
---
Know of any other packages that work with Wagtail 2.11 that should be mentioned? Contact Kalob to update this list.
---
Kalob Taulien
Wagtail CMS enthusiast; Wagtail core team member; Coding teacher.