### 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. - If you're using `RichTextField` or a `RichTextBlock`, which you probably are, you'll want to take a look at [this documentation surrounding `.rich-text`](https://docs.wagtail.org/en/stable/releases/2.10.html#div-class-rich-text-wrappers-removed-from-rich-text) ### 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. ---