### Step-by-Step Upgrade to Wagtail 2.15 LTS Upgrading your CMS to Wagtail 2.15 LTS is an essential task that ensures your website remains up-to-date with the latest improvements and security patches. This version jump might seem daunting due to the numerous changes across multiple versions, but with a clear step-by-step approach, it can be manageable. ### Understanding Version Changes Before initiating the upgrade, it's important to review the changes that each version introduces. This helps prepare for any necessary adjustments in your code or third-party packages. - **Wagtail 2.12:** This release removes support for Elasticsearch 2. If your project uses Elasticsearch, upgrading to a supported version is necessary. [Read the Wagtail 2.12 release notes for more details.](https://docs.wagtail.org/en/stable/releases/2.12.html#upgrade-considerations) - **Wagtail 2.13:** One of the noteworthy changes here is the end of support for Internet Explorer 11. This change simplifies development since you no longer need to maintain compatibility with IE11. [Check out the Wagtail 2.13 release notes.](https://docs.wagtail.org/en/stable/releases/2.13.html#upgrade-considerations) - **Wagtail 2.14:** This version marks the end of support for Django 2.2. Additionally, changes in external platforms like Facebook and Instagram affect content embedding features. [Wagtail 2.14 release notes provide further insights.](https://docs.wagtail.org/en/stable/releases/2.14.html#upgrade-considerations) - **Wagtail 2.15:** The introduction of the “Component” class affects admin homepage panels and summary items, which may require updates to your custom admin interface. [Detailed upgrade considerations can be found in the Wagtail 2.15 release notes.](https://docs.wagtail.org/en/stable/releases/2.15.html#upgrade-considerations) ### Upgrading Django and Python Since Wagtail 2.15 LTS supports newer versions of Django and Python, it’s a good opportunity to upgrade these components: - Update your `requirements.txt` to include Django 3.0.* and the specific Wagtail version: ```plaintext # requirements.txt Django==3.0.* wagtail==2.15.6 ``` ### Checking Other Dependencies Other dependencies in your project might need updates to be compatible with Django 3.0 and Wagtail 2.15. For example: - If you’re using `django-el-pagination` or `django-recaptcha`, check their compatibility on PyPI or their GitHub repositories. Look for the latest versions that support Django 3.0. If necessary, consult the `setup.py` in these repositories to verify Django version requirements. ### Addressing Errors and Migrations Once Wagtail 2.15.6 and Django 3.0.14 are set up, you might encounter various errors upon running your project. Common issues include deprecated or moved modules: - Update imports that have changed, for example: ```python # Change from django.contrib.staticfiles.templatetags.staticfiles import static # To from django.templatetags.static import static ``` - Remove references to outdated Python 2 compatibility layers, like `python_2_unicode_compatible`, as Python 3 is now fully supported and required. ### Running Migrations After making adjustments based on the errors encountered, perform database migrations to apply changes: ```bash python manage.py migrate ``` This step is crucial for updating the database schema to match the new application state. ### Handling Third-Party Package Errors If further issues arise, they are likely due to third-party packages that need updates or replacements. Assess each package's necessity, updating or removing as needed to ensure compatibility with the new Wagtail and Django versions. --- ### Noteworthy gotchas: #### Curry If you see this: ```plaintext ImportError: cannot import name 'curry' from 'django.utils.functional' (/opt/venv/lib/python3.8/site-packages/django/utils/functional.py) ``` Then you likely need to upgrade a package. It says it's from Django, but a little digging revealed it was `django-adminactions`. A quick `pip install django-adminactions==1.15` solve this problem. #### Admin Static If you see this: ```plaintext ModuleNotFoundError: No module named 'django.contrib.admin.templatetags.admin_static' ``` Chances are that is also a 3rd party package that needs to be upgraded. In my case, this was `django-extensions` that needed to be upgraded a version point.