Add 'undocumented internals' section to 5.2 upgrade considerations

docs/releases/5.2.md

@@ -219,6 +219,99 @@ If using custom styling for the breadcrumbs, this class has changed from singula
 | ---------------- | ----------------- |
 | `'w-breadcrumb'` | `'w-breadcrumbs'` |
 
+### Snippets templates refactored to reuse the shared `slim_header.html` template
+
+The templates for the snippets views have been refactored to reuse the shared `slim_header.html` template. If you have customised or extended the templates, e.g. for [](wagtailsnippets_custom_admin_views), you will need to update them to match the new structure. As a result, the following templates have been removed:
+
+- `wagtailsnippets/snippets/headers/_base_header.html`
+- `wagtailsnippets/snippets/headers/create_header.html`
+- `wagtailsnippets/snippets/headers/edit_header.html`
+- `wagtailsnippets/snippets/headers/history_header.html`
+- `wagtailsnippets/snippets/headers/list_header.html`
+- `wagtailsnippets/snippets/headers/usage_header.html`
+
+In most cases, the usage of those templates can be replaced with the `wagtailadmin/shared/headers/slim_header.html` template. Refer to the snippets views and templates code for more details.
+
+### `BaseSidePanels`, `PageSidePanels` and `SnippetSidePanels` classes are removed
+
+The `BaseSidePanels`, `PageSidePanels` and `SnippetSidePanels` classes that were used to combine the side panels (i.e. status, preview and comments side panels) have been removed. Each side panel is now instantiated directly in the view. The `wagtail.admin.ui.components.MediaContainer` class can be used to combine the [`Media`](django:topics/forms/media) objects for the side panels.
+
+The `BasePreviewSidePanel`, `PagePreviewSidePanel` and `SnippetPreviewSidePanel` classes have been replaced with the consolidated `PreviewSidePanel` class.
+
+The `BaseStatusSidePanel` class has been renamed to `StatusSidePanel`.
+
+If you use these classes in your code, you will need to update your code to instantiate the side panels directly in the view.
+
+For example, if you have the following code:
+
+```python
+from wagtail.admin.ui.side_panels import PageSidePanels
+
+
+def my_view(request):
+    ...
+
+    side_panels = PageSidePanels(
+        request,
+        page.get_latest_revision_as_object(),
+        show_schedule_publishing_toggle=False,
+        live_page=page,
+        scheduled_page=page.get_scheduled_revision_as_object(),
+        in_explorer=False,
+        preview_enabled=True,
+        comments_enabled=False,
+    )
+
+    return render(
+        request,
+        template_name,
+        {"page": page, "side_panels": side_panels, "media": side_panels.media},
+    )
+```
+
+Update it to the following:
+
+```python
+from wagtail.admin.ui.components import MediaContainer
+from wagtail.admin.ui.side_panels import PageStatusSidePanel, PreviewSidePanel
+
+
+def my_view(request):
+    ...
+
+    side_panels = [
+        PageStatusSidePanel(
+            page,
+            request,
+            show_schedule_publishing_toggle=False,
+            live_object=page,
+            scheduled_object=page.get_scheduled_revision_as_object(),
+            locale=page.locale,
+            translations=translations,
+        ),
+        PreviewSidePanel(
+            page,
+            request,
+            preview_url=reverse("wagtailadmin_pages:preview_on_edit", args=[page.id]),
+        ),
+    ]
+    side_panels = MediaContainer(side_panels)
+
+    return render(
+        request,
+        template_name,
+        {"page": page, "side_panels": side_panels, "media": side_panels.media},
+    )
+```
+
+### `construct_snippet_listing_buttons` hook no longer accepts a `context` argument
+
+The [`construct_snippet_listing_buttons`](construct_snippet_listing_buttons) hook no longer accepts a `context` argument. If you have implemented this hook, you will need to remove the `context` argument from your implementation. If you need to access values computed by the view, you'll need to override the {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.index_view_class` with a custom `IndexView` subclass. The `get_list_buttons` and `get_list_more_buttons` methods in particular may be overridden to customise the buttons on the listing.
+
+Defining a function for this hook that accepts the `context` argument will raise a warning, and the function will receive an empty dictionary (`{}`) as the `context`. Support for defining the `context` argument will be completely removed in a future Wagtail release.
+
+## Upgrade considerations - changes to undocumented internals
+
 ### Breadcrumbs now use different data attributes and events
 
 The undocumented JavaScript implementation for the header breadcrumbs component has been migrated to a Stimulus controller and now uses different data attributes.
@@ -274,19 +367,6 @@ window.updateFooterSaveWarning = (formDirty, commentsDirty) => {
 };
 ```
 
-### Snippets templates refactored to reuse the shared `slim_header.html` template
-
-The templates for the snippets views have been refactored to reuse the shared `slim_header.html` template. If you have customised or extended the templates, e.g. for [](wagtailsnippets_custom_admin_views), you will need to update them to match the new structure. As a result, the following templates have been removed:
-
-- `wagtailsnippets/snippets/headers/_base_header.html`
-- `wagtailsnippets/snippets/headers/create_header.html`
-- `wagtailsnippets/snippets/headers/edit_header.html`
-- `wagtailsnippets/snippets/headers/history_header.html`
-- `wagtailsnippets/snippets/headers/list_header.html`
-- `wagtailsnippets/snippets/headers/usage_header.html`
-
-In most cases, the usage of those templates can be replaced with the `wagtailadmin/shared/headers/slim_header.html` template. Refer to the snippets views and templates code for more details.
-
 ### `dropdown` template tag argument `toggle_tippy_offset` renamed to `toggle_tooltip_offset`
 
 The naming conventions for `tippy` related attributes have been updated to align with the generic `tooltip` naming.
@@ -328,84 +408,6 @@ Use the HTML [`template`](https://developer.mozilla.org/en-US/docs/Web/HTML/Elem
 </template>
 ```
 
-### `BaseSidePanels`, `PageSidePanels` and `SnippetSidePanels` classes are removed
-
-The `BaseSidePanels`, `PageSidePanels` and `SnippetSidePanels` classes that were used to combine the side panels (i.e. status, preview and comments side panels) have been removed. Each side panel is now instantiated directly in the view. The `wagtail.admin.ui.components.MediaContainer` class can be used to combine the [`Media`](django:topics/forms/media) objects for the side panels.
-
-The `BasePreviewSidePanel`, `PagePreviewSidePanel` and `SnippetPreviewSidePanel` classes have been replaced with the consolidated `PreviewSidePanel` class.
-
-The `BaseStatusSidePanel` class has been renamed to `StatusSidePanel`.
-
-If you use these classes in your code, you will need to update your code to instantiate the side panels directly in the view.
-
-For example, if you have the following code:
-
-```python
-from wagtail.admin.ui.side_panels import PageSidePanels
-
-
-def my_view(request):
-    ...
-
-    side_panels = PageSidePanels(
-        request,
-        page.get_latest_revision_as_object(),
-        show_schedule_publishing_toggle=False,
-        live_page=page,
-        scheduled_page=page.get_scheduled_revision_as_object(),
-        in_explorer=False,
-        preview_enabled=True,
-        comments_enabled=False,
-    )
-
-    return render(
-        request,
-        template_name,
-        {"page": page, "side_panels": side_panels, "media": side_panels.media},
-    )
-```
-
-Update it to the following:
-
-```python
-from wagtail.admin.ui.components import MediaContainer
-from wagtail.admin.ui.side_panels import PageStatusSidePanel, PreviewSidePanel
-
-
-def my_view(request):
-    ...
-
-    side_panels = [
-        PageStatusSidePanel(
-            page,
-            request,
-            show_schedule_publishing_toggle=False,
-            live_object=page,
-            scheduled_object=page.get_scheduled_revision_as_object(),
-            locale=page.locale,
-            translations=translations,
-        ),
-        PreviewSidePanel(
-            page,
-            request,
-            preview_url=reverse("wagtailadmin_pages:preview_on_edit", args=[page.id]),
-        ),
-    ]
-    side_panels = MediaContainer(side_panels)
-
-    return render(
-        request,
-        template_name,
-        {"page": page, "side_panels": side_panels, "media": side_panels.media},
-    )
-```
-
-### `construct_snippet_listing_buttons` hook no longer accepts a `context` argument
-
-The [`construct_snippet_listing_buttons`](construct_snippet_listing_buttons) hook no longer accepts a `context` argument. If you have implemented this hook, you will need to remove the `context` argument from your implementation. If you need to access values computed by the view, you'll need to override the {attr}`~wagtail.snippets.views.snippets.SnippetViewSet.index_view_class` with a custom `IndexView` subclass. The `get_list_buttons` and `get_list_more_buttons` methods in particular may be overridden to customise the buttons on the listing.
-
-Defining a function for this hook that accepts the `context` argument will raise a warning, and the function will receive an empty dictionary (`{}`) as the `context`. Support for defining the `context` argument will be completely removed in a future Wagtail release.
-
 ### Adoption of `classname` convention within the Image `Format` instance
 
 When using `wagtail.images.formats.Format`, the created instance set the argument for classes to the attribute `classnames` (plural), this has now changed to `classname` (singular).