Move workflow upgrade considerations to 2.10

docs/releases/2.10.rst

@@ -123,6 +123,30 @@ In previous releases, rich text values were enclosed in a ``<div class="rich-tex
 To restore the old behaviour, see :ref:`legacy_richtext`.
 
 
+Move to new configurable moderation system (workflow)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new workflow system has been introduced for moderation. Task types are defined as models in code, and instances - tasks - are created in the Wagtail Admin,
+then chained together to form workflows: sequences of moderation stages through which a page must pass prior to publication.
+
+Key points:
+
+* Prior to 2.9, moderation in Wagtail was performed on a per-revision basis: once submitted, the moderator would approve or reject
+  the submitted revision only, which would not include subsequent changes. Moderation is now performed per page, with moderators
+  always seeing the latest revision.
+* ``PageRevision.submitted_for_moderation`` will return ``True`` for revisions passing through the old moderation system, but not for the new system
+* Pages undergoing moderation in the old system will not have their moderation halted, and can still be approved/rejected. As a result, you may see
+  two sets of moderation dashboard panels until there are no longer any pages in moderation in the old system
+* No pages can be submitted for moderation in the old system: "Submit for moderation" now submits to the new Workflow system
+* You no longer need the publish permission to perform moderation actions on a page - actions available to each user are now configured per task.
+  With the built in ``GroupApprovalTask``, anybody in a specific set of groups can approve or reject the task.
+* A data migration is provided to recreate your existing publish-permission based moderation workflow in the new system. If you have made no permissions changes,
+  this should simply create a task approvable by anybody in the `Moderators` group, and assign a workflow with this task to the root page, creating a standard workflow
+  for the entire page tree. However, if you have a complex nested set of publish page permissions, the created set of workflows will be more complex as well - you may wish to
+  inspect the created workflows and tasks in the new ``Settings/Workflows`` admin area and potentially simplify them.
+  See :ref:`managing_workflows` for the administrator guide.
+
+
 New ``next_url`` keyword argument on ``register_page_listing_buttons`` and ``register_page_listing_more_buttons`` hooks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/releases/2.9.rst

@@ -99,27 +99,3 @@ Page / Collection managers no longer expose a ``delete`` method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 For `consistency with standard Django models <https://docs.djangoproject.com/en/stable/topics/db/queries/#deleting-objects>`_, the ``delete()`` method is no longer available on the default Page and Collection managers. Code such as ``Page.objects.delete()`` should be changed to ``Page.objects.all().delete()``.
-
-
-Move to new configurable moderation system (workflow)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A new workflow system has been introduced for moderation. Task types are defined as models in code, and instances - tasks - are created in the Wagtail Admin,
-then chained together to form workflows: sequences of moderation stages through which a page must pass prior to publication.
-
-Key points:
-
-* Prior to 2.9, moderation in Wagtail was performed on a per-revision basis: once submitted, the moderator would approve or reject
-  the submitted revision only, which would not include subsequent changes. Moderation is now performed per page, with moderators
-  always seeing the latest revision.
-* ``PageRevision.submitted_for_moderation`` will return ``True`` for revisions passing through the old moderation system, but not for the new system
-* Pages undergoing moderation in the old system will not have their moderation halted, and can still be approved/rejected. As a result, you may see
-  two sets of moderation dashboard panels until there are no longer any pages in moderation in the old system
-* No pages can be submitted for moderation in the old system: "Submit for moderation" now submits to the new Workflow system
-* You no longer need the publish permission to perform moderation actions on a page - actions available to each user are now configured per task.
-  With the built in ``GroupApprovalTask``, anybody in a specific set of groups can approve or reject the task.
-* A data migration is provided to recreate your existing publish-permission based moderation workflow in the new system. If you have made no permissions changes,
-  this should simply create a task approvable by anybody in the `Moderators` group, and assign a workflow with this task to the root page, creating a standard workflow
-  for the entire page tree. However, if you have a complex nested set of publish page permissions, the created set of workflows will be more complex as well - you may wish to
-  inspect the created workflows and tasks in the new ``Settings/Workflows`` admin area and potentially simplify them.
-  See :ref:`managing_workflows` for the administrator guide.