From 9a953fd93cccb8288d4399d94240976d3a14e2fa Mon Sep 17 00:00:00 2001 From: Matt Westcott Date: Tue, 8 Dec 2020 16:00:47 +0000 Subject: [PATCH] Additional release notes for #6559 --- CHANGELOG.txt | 6 ++++++ docs/releases/2.11.3.rst | 40 ++++++++++++++++++++++++---------------- docs/releases/2.11.rst | 32 ++++++++++++++++++++++++++++++++ docs/releases/index.rst | 1 + 4 files changed, 63 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 31b604d70a..cbc12fbc9b 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -10,6 +10,12 @@ Changelog * Fix: Make sure document chooser pagination preserves the selected collection when moving between pages (Alex Sa) +2.11.3 (xx.xx.xxxx) - IN DEVELOPMENT +~~~~~~~~~~~~~~~~~~~ + + * Fix: Updated project template migrations to ensure that initial homepage creation runs before addition of locale field (Dan Braghis) + + 2.11.2 (17.11.2020) ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/2.11.3.rst b/docs/releases/2.11.3.rst index 3679e41617..fb09347607 100644 --- a/docs/releases/2.11.3.rst +++ b/docs/releases/2.11.3.rst @@ -1,6 +1,6 @@ -============================ -Wagtail 2.11.3 release notes -============================ +============================================= +Wagtail 2.11.3 release notes - IN DEVELOPMENT +============================================= .. contents:: :local: @@ -13,16 +13,16 @@ What's new Bug fixes ~~~~~~~~~ - * + * Updated project template migrations to ensure that initial homepage creation runs before addition of locale field (Dan Braghis) Upgrade considerations ====================== -If you have used the Wagtail project template, or have migrations that create page instances programmatically, you will -need to add ``run_before = [('wagtailcore', '0053_locale_model')]`` to the corresponding ``Migration`` class. +``run_before`` declaration needed in initial homepage migration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For example, ``0002_create_homepage.py`` (from the project template): +The migration that creates the initial site homepage needs to be updated to ensure that will continue working under Wagtail 2.11. If you have kept the ``home`` app from the original project layout generated by the ``wagtail start`` command, this will be ``home/migrations/0002_create_homepage.py``. Inside the ``Migration`` class, add the line ``run_before = [('wagtailcore', '0053_locale_model')]`` - for example: .. code-block:: python @@ -30,14 +30,22 @@ For example, ``0002_create_homepage.py`` (from the project template): class Migration(migrations.Migration): - run_before = [ - ('wagtailcore', '0053_locale_model'), # added for Wagtail 2.11 compatibility - ] + run_before = [ + ('wagtailcore', '0053_locale_model'), # added for Wagtail 2.11 compatibility + ] - dependencies = [ - ('home', '0001_initial'), - ] + dependencies = [ + ('home', '0001_initial'), + ] - operations = [ - migrations.RunPython(create_homepage, remove_homepage), - ] + operations = [ + migrations.RunPython(create_homepage, remove_homepage), + ] + +This fix applies to any migration that creates page instances programmatically. If you installed Wagtail into an existing Django project by following the instructions at :doc:`../getting_started/integrating_into_django`, you most likely created the initial homepage manually, and no change is required in this case. + +**Further background:** Wagtail 2.11 adds a ``locale`` field to the Page model, and since the existing migrations in your project pre-date this, they are designed to run against a version of the Page model that has no ``locale`` field. As a result, they need to run before the new migrations that have been added to ``wagtailcore`` within Wagtail 2.11. However, in the old version of the homepage migration, there is nothing to ensure that this sequence is followed. The actual order chosen is an internal implementation detail of Django, and in particular is liable to change as you continue developing your project under Wagtail 2.11 and create new migrations that depend on the current state of ``wagtailcore``. In this situation, a user installing your project on a clean database may encounter the following error when running ``manage.py migrate``:: + + django.db.utils.IntegrityError: NOT NULL constraint failed: wagtailcore_page.locale_id + +Adding the ``run_before`` directive will ensure that the migrations run in the intended order, avoiding this error. diff --git a/docs/releases/2.11.rst b/docs/releases/2.11.rst index ee429c3a24..34a39988bb 100644 --- a/docs/releases/2.11.rst +++ b/docs/releases/2.11.rst @@ -102,6 +102,38 @@ Bug fixes Upgrade considerations ====================== +``run_before`` declaration needed in initial homepage migration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The migration that creates the initial site homepage needs to be updated to ensure that will continue working under Wagtail 2.11. If you have kept the ``home`` app from the original project layout generated by the ``wagtail start`` command, this will be ``home/migrations/0002_create_homepage.py``. Inside the ``Migration`` class, add the line ``run_before = [('wagtailcore', '0053_locale_model')]`` - for example: + +.. code-block:: python + + # ... + + class Migration(migrations.Migration): + + run_before = [ + ('wagtailcore', '0053_locale_model'), # added for Wagtail 2.11 compatibility + ] + + dependencies = [ + ('home', '0001_initial'), + ] + + operations = [ + migrations.RunPython(create_homepage, remove_homepage), + ] + +This fix applies to any migration that creates page instances programmatically. If you installed Wagtail into an existing Django project by following the instructions at :doc:`../getting_started/integrating_into_django`, you most likely created the initial homepage manually, and no change is required in this case. + +**Further background:** Wagtail 2.11 adds a ``locale`` field to the Page model, and since the existing migrations in your project pre-date this, they are designed to run against a version of the Page model that has no ``locale`` field. As a result, they need to run before the new migrations that have been added to ``wagtailcore`` within Wagtail 2.11. However, in the old version of the homepage migration, there is nothing to ensure that this sequence is followed. The actual order chosen is an internal implementation detail of Django, and in particular is liable to change as you continue developing your project under Wagtail 2.11 and create new migrations that depend on the current state of ``wagtailcore``. In this situation, a user installing your project on a clean database may encounter the following error when running ``manage.py migrate``:: + + django.db.utils.IntegrityError: NOT NULL constraint failed: wagtailcore_page.locale_id + +Adding the ``run_before`` directive will ensure that the migrations run in the intended order, avoiding this error. + + IE11 support being phased out ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/index.rst b/docs/releases/index.rst index b92e4b4b00..37b15ff5bb 100644 --- a/docs/releases/index.rst +++ b/docs/releases/index.rst @@ -6,6 +6,7 @@ Release notes upgrading 2.12 + 2.11.3 2.11.2 2.11.1 2.11