From 7c22b4aaaa9639fd2e9c3b9ec26b0e54b3acca48 Mon Sep 17 00:00:00 2001
From: Sage Abdullah <sage.abdullah@torchbox.com>
Date: Mon, 2 Oct 2023 10:34:31 +0100
Subject: [PATCH] Add upgrade considerations for side panels refactoring

---
 docs/releases/5.2.md | 70 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/docs/releases/5.2.md b/docs/releases/5.2.md
index c9660a535f..552fa21a1a 100644
--- a/docs/releases/5.2.md
+++ b/docs/releases/5.2.md
@@ -248,3 +248,73 @@ Use the HTML [`template`](https://developer.mozilla.org/en-US/docs/Web/HTML/Elem
     <script src="/js/my-widget.js"></script>
 </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.
+
+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},
+    )
+```