Wagtail upgrades

Nobody decides to fall behind. It happens because an upgrade has no deadline — nothing breaks on the day you skip one. So the release notes pile up, each skipped version makes the next one harder, and eventually the gap is wide enough that the upgrade looks like a rewrite. At that point it stops being scheduled at all.

Three things usually turn out to be doing the actual blocking:

• Third-party packages, not Wagtail. Wagtail's own upgrade path is well documented and largely mechanical. What pins you to a version is the layer of packages on top of it — and a good share of those turn out to be unmaintained, or replaceable with a few dozen lines of your own code.
• No tests. An upgrade you cannot verify is an upgrade you cannot ship. This is usually the real cost of the work, and it is worth paying whether or not you go ahead with the upgrade.
• Rendering libraries you had forgotten were there. Wagtail's rich text is converted to HTML by draftjs-exporter. A single Wagtail upgrade can move that library five major versions, and no release note will tell you what your content looks like afterwards.

Release by release, never in one jump.

1. Read the actual state first. Which Wagtail and Django versions, which third-party packages, whether there are unapplied migrations already sitting in the repository — there often are — and whether manage.py check is clean today.
2. Put the safety net in before anything moves. Enough tests to prove that the pages that matter still render, the forms still submit and the search still returns results. On a site with no tests, that is the first commit, not an afterthought.
3. One version at a time, each its own commit — and its own deploy, if that is how you would rather do it. Every step gets a makemigrations --check, a full test run, and a rendered diff of the real pages against production.
4. Prove the content, not just the code. The rich text, the StreamField blocks, the image renditions. This is where an upgrade that passes every test still quietly changes what visitors see.
5. Choose LTS or latest deliberately. A Wagtail LTS is supported for about a year; a regular release for a matter of months. Which one you want depends on whether you would rather upgrade once a year or once a quarter. That is a maintenance-budget decision rather than a technical one, and it should be made on purpose instead of by default.

• A site on a supported Wagtail release, with the security patches that come with it.
• A test suite that did not exist before, and that stays useful long after the upgrade is finished.
• A written record of what changed at each step — which is what makes the next upgrade a smaller job than this one.
• The editor experience from all the versions you skipped. The page editor, previews and admin improvements your team has been reading about and not getting.

The Museum Wilhelm Busch website came across from a small agency in Hanover in 2018 and I have kept it current ever since — one release at a time, for eight years, alongside building a pretix-based ticket shop for entry, exhibitions and vouchers. That is what this work looks like when it is going well: unremarkable.

At Safety.io, a subsidiary of MSA The Safety Company, I took over as lead developer and ran every Django and Wagtail update for the duration of the engagement, alongside a testing and debugging process the project had not had before.

And this site runs Wagtail 8.0. That is not a boast; it is the reason I can tell you what the current release actually breaks, rather than what the release notes predict it will break.

If your Wagtail version has turned into a question rather than a detail, get in touch and say where the project stands. The current Wagtail and Django versions and a rough idea of when it was last upgraded are enough for a useful first conversation — and enough to tell you whether this is a week of work or a quarter of it.