### 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 ... ) ``` ### 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) ``` ### 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.