Before getting started

You will want to bookmark this one particular documentation page:
https://docs.wagtail.org/en/stable/releases/upgrading.html

Also note that I am starting with:

• Wagtail 2.5
• Django 2.2
• Python 3.7

Along the way we will upgrade Django and Python, as well.

Kickstarting the Upgrade from Wagtail 2.5

Upgrading your Wagtail setup is more than just stepping up numbers—it's a perfect chance to tidy up your project! As you embark on this journey from Wagtail 2.5, here are a few things you should consider doing first:

• 🧹 Clean House: Take this moment to remove any unnecessary code. This includes unused imports, cleaning up your codebase, squashing old migrations, ditching unused packages, and streamlining settings files.
• ✅ Test Everything: Make sure your unit tests are up-to-date and passing. This foundational check will save you headaches later!

Upgrade Path Strategy 🛤️

When it comes to actually upgrading Wagtail, you've got a couple of options:

1. Continuous Testing: Run your unit tests at each stage of the upgrade. This method helps catch issues early but can be time-consuming if you're fixing tests frequently.
2. Endgame Testing: Save the bulk of unit testing until after all upgrades are done. This can be more efficient, as you'll avoid revisiting the same test multiple times.

I personally lean towards the second option—waiting until all upgrades are complete before diving into unit testing. It feels more efficient as it prevents you from getting stuck on the same issues repeatedly. However, choose the path that best suits your workflow and team dynamics.

Note: This is a GREAT time to reduce package use that Wagtail supports. For instance you can remove the wagtail-livepreview package in favour of Wagtail's built in live-preview feature.

Upgrading to Wagtail 2.7 LTS

Your first major stop is Wagtail 2.7 LTS. It’s important to note that this version still plays nicely with Django 2.2, keeping things smooth compatibility-wise.

🚀 Launch Check: Before moving beyond Wagtail 2.7 LTS, make sure to do a basic functionality test. Running python manage.py runserver 0.0.0.0:8000 should work without a hitch. Ensuring everything operates correctly at this stage sets a solid foundation for further upgrades.

In the next article, we will install Wagtail 2.7. Thats our first upgrade step.