Upgrading to Wagtail 2.0
Wagtail 2.0 is one of our biggest releases to date, with a focus on making a clean break from legacy design choices and limitations dictated by older versions of Python and Django. As a result, upgrading involves a few more steps than usual - but don't be discouraged. For most sites - assuming they don't rely on heavy customisations to Wagtail internals - it should be a largely mechanical process.
Prerequisites
Before starting the upgrade to Wagtail 2.0, you'll need to be running Django 1.11, and Python 3.4 or above - Python 2 support has been dropped in this release. If you're new to Python 3, What's New In Python 3.0 is a good summary of the changes from Python 2.
Module renaming
One of the longest-standing bugbears in Wagtail has been the wordiness of import lines like from wagtail.wagtailcore.models import Page. This was an artefact of Wagtail's origins on Django 1.6, where the module path had to match the app label, and so the extra 'wagtail' prefix was necessary to avoid clashing with other apps with common names like 'core', 'admin' or 'images'.
Django 1.6 is long gone now, and so we've taken the 2.0 release as an opportunity to drop the 'wagtail' prefix - see the 2.0 release notes for the complete list of renamed modules. The wagtail updatemodulepaths command can be used to automatically convert all module references across your project:
- wagtail updatemodulepaths (run from the root of your project) will immediately update your project files in place
- wagtail updatemodulepaths --list and wagtail updatemodulepaths --diff will show a preview of the changes to be made
Keep in mind that this command is only performing basic text replacement on *.py files - if (for example) you have references to Wagtail modules inside shell scripts, or you're doing some particularly exotic string processing to build up INSTALLED_APPS, you'll need to fix these up manually. Also, note that the name change only applies to dotted module paths - there are various other contexts where Wagtail's app labels surface in project code, such as model references in foreign keys, template directories, and tag libraries ({% load wagtailimages_tags %} and so on). These still need to keep the 'wagtail' prefix - otherwise, there'd be no way to distinguish them from non-Wagtail apps such as the Django admin.
At this point it might seem like this is a rather minor change that doesn't justify the hassle of updating, but it all goes towards making Wagtail development as pleasant as it can be, and we believe it's better to get this chore out of the way sooner rather than later to make the project better for everyone. After all, we hope that there'll be an order of magnitude more users of Wagtail 3.0 than 2.0! Normally we'd aim to make this kind of change through a gradual deprecation process, allowing the old version of the code to continue working for a number of releases - but in this case it wasn't possible to do so without awkward hacks, and we felt that it was better to have the old code fail cleanly in a way that made it clear what needs to be fixed, rather than have it carry on working unreliably.
Django 2.0
We'd recommend upgrading to Django 2.0 as a separate step once you're happy that everything is working properly on Wagtail 2.0 and Django 1.11 - this will make fault-finding easier, as you'll be able to tell whether any changes in behaviour are due to Wagtail or Django. The breaking changes in Django 2.0 you're most likely to encounter are on_delete now being required on foreign keys, and the removal of assignment_tag (now absorbed into the functionality of simple_tag), but be sure to consult the Django 2.0 release notes.
Draftail
One of the biggest new features in Wagtail 2.0 is the introduction of Draftail as the new rich text editor. Functionally, Draftail is a drop-in replacement for the old hallo.js-based editor, although internally it works on a very different model. Functionality added through hallo.js plugins will no longer be available, and will need to be rewritten for Draftail's extension model.
Draftail will not necessarily produce identical HTML output to the hallo.js editor, and is likely to differ in details such as whether images are wrapped in paragraph tags. This is expected - rich text has always been designed to provide simple text formatting facilities, not to be a general-purpose HTML authoring tool. We'd encourage the use of StreamField for building page elements that require exact control over HTML structure. However, if this isn't possible, and you're reliant on the specific HTML generated by hallo.js, you can revert to the original editor by adding the following to your settings:
WAGTAILADMIN_RICH_TEXT_EDITORS = { 'default': { 'WIDGET': 'wagtail.admin.rich_text.HalloRichTextArea' } }
Third-party libraries
Naturally, you'll need to make sure that any third-party libraries you're using are also compatible with Wagtail 2.0 and Django 2.0. Many of the most popular Wagtail add-on packages have now been updated with Wagtail 2.0 support, and those which haven't will certainly appreciate a pull request! (Most likely, adding Wagtail 2.0 support will just involve updating the module import paths; to preserve compatibility with earlier versions of Wagtail, we suggest wrapping them in a try / except block to fall back on the old import paths.)
You'll also need to keep an eye on the installed versions of Wagtail's own dependencies, particularly Django REST Framework which added support for Django 2.0 in version 3.7.4. (Wagtail 2.0 did not mandate this version, because earlier versions of Django REST Framework were still compatible when used in conjunction with Django 1.11; as of Wagtail 2.0.1, our version requirements have been tightened up, and will now install version 3.7.4 automatically. However, if your project specifies an exact version in the requirements file, this needs to be updated too.)
Can't upgrade?
While we hope we've made the upgrade path to 2.0 as smooth as possible, we appreciate that there may still be blockers that prevent you from upgrading - the requirement for Python 3 probably being the biggest one. Rest assured that support for Wagtail 1.13 will be continuing for some time yet - like 1.12 we've now designated it a Long Term Support release, and will continue to support it with new patch releases to address security and data loss issues.