Add migration to apply alphabetical collection ordering

docs/releases/2.11.rst

@@ -10,6 +10,12 @@ Wagtail 2.11 release notes - IN DEVELOPMENT
 What's new
 ==========
 
+Collections hierarchy
+~~~~~~~~~~~~~~~~~~~~~
+
+Collections (for organising images, documents or other media) can now be managed as a hierarchy rather than a flat list. This feature was developed by Robert Rollins.
+
+
 Other features
 ~~~~~~~~~~~~~~
 
@@ -59,19 +65,26 @@ SiteMiddleware moved to ``wagtail.contrib.legacy``
 The SiteMiddleware class (which provides the ``request.site`` property, and has been deprecated since Wagtail 2.9) has been moved to the ``wagtail.contrib.legacy`` namespace. On projects where this is still in use, the ``'wagtail.core.middleware.SiteMiddleware'`` entry in ``MIDDLEWARE`` should be changed to ``'wagtail.contrib.legacy.sitemiddleware.SiteMiddleware'``.
 
 
-Run fixtree to prevent Collection creation issues
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Collection model enforces alphabetical ordering
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are using Wagtail's Collections feature to organise images, documents or other media, please ensure
-you run the following command in each environment:
+As part of the hierarchical collections support, the ``path`` field on the Collection model now enforces alphabetical ordering. Previously, collections were stored in the order in which they were created - and then sorted by name where displayed in the CMS. This change will be handled automatically through migrations when upgrading to Wagtail 2.11.
 
-.. code-block:: python
+However, if your project creates new collections programmatically after migrations have run, and assigns the ``path`` field directly - for example, by loading from a fixture file - this code will need to be updated to insert them in alphabetical order. Otherwise, errors may occur when subsequently adding new collections through the Wagtail admin. This can be done as follows:
 
-    python manage.py fixtree --full
+ * Update paths to match alphabetical order. For example, if you have a fixture that creates the collections ``Zebras`` and ``Aardvarks`` with paths ``00010001`` and ``00010002`` respectively, these paths should be swapped.
+ * *Alternatively*, after creating the collections, run the Python code:
 
-Previously, collections were stored in the order in which they were created - and then sorted by name where displayed in the CMS. Collections are now ordered by treebeard path by default, so the above command must be run to retain alphabetical ordering.
+   .. code-block:: python
 
-Failure to do this won't affect your current collections, but may affect your ability to add new ones.
+       from wagtail.core.models import Collection
+       Collection.fix_tree(fix_paths=True)
+
+   or the management command:
+
+   .. code-block:: console
+
+       python manage.py fixtree --full
 
 
 ``Site.get_site_root_paths`` now returns language code

wagtail/core/migrations/0059_apply_collection_ordering.py

@@ -0,0 +1,26 @@
+# Generated by Django 3.1.1 on 2020-09-30 10:14
+
+from django.db import migrations
+
+# import the real Collection model (as opposed to the frozen version we'd obtain with
+# apps.get_model) so that we can use its fix_tree method. Importing real models in migrations is
+# generally avoided since it's liable to generate SQL queries according to the final migrated
+# database state which we haven't reached yet - however, in this case it should be safe because
+# fix_tree only touches the Treebeard-specific fields via values_list and update, and shouldn't be
+# sensitive to schema changes elsewhere.
+from wagtail.core.models import Collection
+
+
+def apply_collection_ordering(apps, schema_editor):
+    Collection.fix_tree(fix_paths=True)
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('wagtailcore', '0058_page_alias_of'),
+    ]
+
+    operations = [
+        migrations.RunPython(apply_collection_ordering, migrations.RunPython.noop),
+    ]