Why we're tackling technical debt in Wagtail 5.0
These are the breaking changes coming in Wagtail 5.0 and how to prepare for them
There have been quite a few updates requiring changes to user code over the 3.x and 4.x releases for Wagtail. Wherever it was possible, we've tried to give people a smooth upgrade path.
For example, when the change from wagtail.core.models to wagtail.models was implemented, we left the old code paths in place so that things didn't immediately break after an upgrade. We did that to give people a window of time to upgrade their code.
However, we've had a steady accumulation of fallback code that's making the codebase more difficult to maintain. That's why we've chosen the next release to be the one where we will drop that fallback code and why we're designating the next release as Wagtail 5.0.
I know many people have mixed feelings about a major version bump. It's a signal that there's going to be some disruption, even if there are exciting new features to reward that disruption. We ultimately adopted semantic versioning for our releases so that the version number is more of a tool for communicating breaking changes than it is a marketing indicator for new features.
If you've kept up with the changes mentioned in release notes in earlier versions, then you've likely already made the changes you need to make for Wagtail 5.0 and will definitely be ready for the breaking changes we're introducing.
The majority of the deprecations that would affect oridinary Wagtail sites were introduced in Wagtail 3.0. So by the time Wagtail 5.0 comes out, you will have had at least a year to make those updates. Even if you still are running older versions and need to catch up with your upgrades, we do maintain detailed release notes in our archives. You can also consider upgrading first to our latest long-term support release, Wagtail Version 4.1, to give yourself more time to prepare for the changes in Wagtail 5.0.
One area where there might be more friction is in third-party packages. It's the eternal problem of open source that people often put things out into the world but aren't able to commit resources to keeping them up to date on an ongoing basis. So, package maintainers may not have been able to stay on top of those incremental updates.
One initiative to address this is the wagtail-nest organisation on Github. Through this, many of the more popular add-on packages are in the process of being upgraded for 3.0, 4.0 and beyond. Please consider joining the effort if you're interested in packages and are looking for opportunities to contribute.
Overall, the motivation for the upcoming 5.0 release is not about us making big bombastic changes. Instead, we're taking an opportunity to clean up some cruft in the Wagtail project at a moment when that will minimise disruption and help us move some other things forward.
We anticipate that we will have a release candidate for Wagtail 5.0 available for testing around 19th April. As usual, we welcome everyone to test it and we look forward to your feedback.
Additional editing and copy for this post were provided by Meagen Voss