### Moving Up to Wagtail 3.0 The transition to Wagtail 3.0 is more than just a routine upgrade—it introduces a series of significant changes that can affect all aspects of your project. This version steps away from some older practices and aligns more closely with recent Django features and best practices. ### Key Changes in Wagtail 3.0 Before diving into the specific changes, always start by reviewing the [upgrade considerations](https://docs.wagtail.org/en/stable/releases/3.0.html#upgrade-considerations-changes-affecting-all-projects) thoroughly to understand how the new features and modifications might impact your project. #### Major Panel Updates Wagtail 3.0 has streamlined how panels are used in the admin by replacing `StreamFieldPanel`, `RichTextFieldPanel`, `ImageChooserPanel`, `DocumentChooserPanel`, and `SnippetChooserPanel` with a unified `FieldPanel`. This change simplifies the model definitions and allows `FieldPanel` to accept its own permissions—a significant enhancement for managing content access. #### Module Path Changes A lot of internal module paths have changed with this release. It’s important to update these paths in your project to ensure everything functions correctly after the upgrade. #### SQLite Requirement For those using SQLite, Wagtail 3.0 now requires the JSON1 extension to be enabled, which supports more advanced data handling directly in the database. [More on this SQLite change](https://docs.wagtail.org/en/stable/releases/3.0.html#sqlite-now-requires-the-json1-extension-enabled). #### Dropping IE11 Support Wagtail 3.0 has officially dropped any lingering support for Internet Explorer 11, aligning with modern web standards and security practices. ### Updating Dependencies and Code With these changes in mind, let’s start updating the project: #### Update `requirements.txt` Your project's dependencies need to reflect the versions compatible with Wagtail 3.0: ``` # requirements.txt wagtail==3.0.3 Django==4.0.10 ``` For those utilizing `django-el-pagination`, ensure you update to a version that supports Django 4.0, such as `django-el-pagination==4.0.0`. #### Replace Deprecated Translation Tags The upgrade to Django 4.0 means updating deprecated translation functions. Replace `ugettext_lazy` with `gettext_lazy`, and make similar updates for `ungettext` and `ugettext`. Examples below: Replace `ungettext` with `ngettext` as seen below: ``` from django.utils.translation import ungettext ``` ☝️ Turns into: 👇 ``` from django.utils.translation import ngettext ``` And also: ``` from django.utils.translation import ugettext as _ ``` ☝️ Turns into: 👇 ``` from django.utils.translation import gettext as _ ``` #### URL Configuration Updates If your `urls.py` uses the old `url()` function, it’s time to switch to `path()` for cleaner and more modern URL routing: ```python # urls.py from django.urls import path, include # Update URL patterns to use path() instead of url() urlpatterns = [ path("django-admin/", admin.site.urls), path("admin/", include(wagtailadmin_urls)), path("api/v2/", api_router.urls), path("sitemap.xml", sitemap), ... ] ``` #### Handling AJAX Requests With the removal of `is_ajax()` in Django 4.0, you'll need to adjust how AJAX requests are detected: ```python if request.headers.get('X-Requested-With') == 'XMLHttpRequest': ... ``` Of course, if you're not detecting `request.is_ajax()` anywhere, then please ignore this part. As fas I understand, `request.is_ajax()` was mainly created to support jQuery. #### Utilizing JSONFields Wagtail 3.0 supports JSONFields, which are more efficient for storing structured data compared to the previous method of using text fields for JSON blobs. To take advantage of this, update your StreamFields: ```python StreamField(..., use_json_field=True) ``` Make and apply migrations to incorporate these changes into your database schema. ```plaintext python manage.py makemigrations python manage.py migrate ``` ### Running the Wagtail Updatemodulepaths Tool To address the numerous module path changes, Wagtail provides a helpful command: ``` wagtail updatemodulepaths ``` This tool will automatically update your import statements throughout your project to reflect the new paths. **Yes, it will make changes to your migration files. This is OK. 👌** ### Finalizing the Upgrade After making these updates, thoroughly test your project to catch any issues that might arise from the changes. Adjust any third-party packages or custom code to ensure full compatibility with Wagtail 3.0 and Django 4.0. By carefully following these steps and utilizing the resources Wagtail provides, you can successfully upgrade to Wagtail 3.0, taking full advantage of its new features and improvements.