Add upgrade considerations for legacy moderation system deprecation

docs/releases/5.2.md

@@ -154,6 +154,31 @@ def register_frank_menu_item():
 
 ## Upgrade considerations - deprecation of old functionality
 
+### Legacy moderation system is deprecated
+
+The legacy moderation system, which was replaced by the new workflow system in Wagtail 2.10, is now deprecated. Since Wagtail 2.10, submitting a page for moderation will use the new workflow system. However, the legacy moderation system is still in place for approving and rejecting pages that were submitted for moderation before Wagtail 2.10.
+
+To view all pages that are still in the legacy moderation system backlog, you can sign in as a superuser and see if there is a "Pages awaiting moderation" section in the admin dashboard. You can approve or reject the pages from there. You can also do this programmatically by querying for `Revision.objects.filter(submitted_for_moderation=True)` and calling `revision.approve_moderation()` or `revision.reject_moderation()` on each revision.
+
+The legacy moderation system will be removed in a future release. If you still have pages in the moderation queue that were submitted for moderation before Wagtail 2.10, you should approve or reject them before upgrading. See [](./2.10) for more details.
+
+As a result, the following features are now deprecated:
+
+- {attr}`wagtail.models.Revision.submitted_for_moderation`
+- {attr}`wagtail.models.Revision.submitted_revisions`
+- {meth}`wagtail.models.Revision.approve_moderation`
+- {meth}`wagtail.models.Revision.reject_moderation`
+- The `submitted_for_moderation` argument in {meth}`wagtail.models.RevisionMixin.save_revision`
+- [`WAGTAIL_MODERATION_ENABLED`](wagtail_moderation_enabled)
+- `wagtail.admin.userbar.ModeratePageItem`
+- `wagtail.admin.userbar.ApproveModerationEditPageItem`
+- `wagtail.admin.userbar.RejectModerationEditPageItem`
+- `wagtail.admin.views.home.PagesForModerationPanel`
+- `wagtail.admin.views.pages.moderation`
+- `wagtail.permission_policies.pages.PagePermissionPolicy.revisions_for_moderation`
+
+If you use any of the above features, remove them or replace them with the equivalent features from the new workflow system. The above features will be removed in a future release.
+
 ## Upgrade considerations - changes affecting Wagtail customisations
 
 ### Edit and delete URLs in `ModelViewSet` changed to allow non-integer primary keys