Update release notes for #8110

docs/releases/2.17.md

@@ -116,15 +116,27 @@ wagtail updatemodulepaths  # actually update the files
 * We encourage all users of the Hallo editor to take steps to migrate to the new Draftail editor as this external package is unlikely to have ongoing maintenance.
 * `window.registerHalloPlugin` will no longer be created on the page editor load, unless the legacy package is installed.
 
-### Phasing-out of special-purpose field panel types
+### API changes to panels (EditHandlers)
 
-As of this release, the use of special-purpose field panel types such as `StreamFieldPanel` and `ImageChooserPanel` is being phased out, and developers will generally expect to be able to use a plain `FieldPanel` instead. For this reason, developers of third-party packages implementing their own field panel types are recommended to follow suit and ensure that their code also works with `FieldPanel`. The steps for doing this will depend on the package's functionality, but in general:
+Various changes have been made to the internal API for defining panel types, previously known as edit handlers. As noted above, the module `wagtail.admin.edit_handlers` has been renamed to `wagtail.admin.panels`, and `wagtail.contrib.forms.edit_handlers` is renamed to `wagtail.contrib.forms.panels`.
+
+Additionally, the base `wagtail.admin.edit_handlers.EditHandler` class has been renamed to `wagtail.admin.panels.Panel`, and `wagtail.admin.edit_handlers.BaseCompositeEditHandler` has been renamed to `wagtail.admin.panels.PanelGroup`.
+
+Template paths have also been renamed accordingly - templates previously within `wagtailadmin/edit_handlers/` are now located under `wagtailadmin/panels/`, and `wagtailforms/edit_handlers/form_responses_panel.html` is now at `wagtailforms/panels/form_responses_panel.html`.
+
+Where possible, third-party packages that implement their own field panel types should be updated to allow using a plain `FieldPanel` instead, in line with Wagtail dropping its own special-purpose field panel types such as `StreamFieldPanel` and `ImageChooserPanel`. The steps for doing this will depend on the package's functionality, but in general:
 
  * If the panel sets a custom template, your code should instead define [a `Widget` class](https://docs.djangoproject.com/en/stable/ref/forms/widgets/) that produces your desired HTML rendering.
  * If the panel provides a `widget_overrides` method, your code should instead call [`register_form_field_override`](/extending/forms) so that the desired widget is always selected for the relevant model field type.
  * If the panel provides a `get_comparison_class` method, your code should instead call `wagtail.admin.compare.register_comparison_class` to register the comparison class against the relevant model field type.
 
-If you do continue to use a custom panel class, note that the template context for panels derived from `BaseChooserPanel` has changed. `BaseChooserPanel` is deprecated and now functionally identical to `FieldPanel`; as a result, the context variable `is_chosen`, and the variable name given by the panel's `object_type_name` property, are no longer available on the template. The only available variables are now `field` and `show_add_comment_button`. If your template depends on these additional variables, you will need to pass them explicitly by overriding the `render_as_field` method.
+Within the `Panel` class, the methods `widget_overrides`, `required_fields` and `required_formsets` have been deprecated in favour of a new `get_form_options` method that returns a dict of configuration options to be passed on to the generated form class:
+
+ * Panels that define `required_fields` should instead return this value as a `fields` item in the dict returned from `get_form_options`
+ * Panels that define `required_formsets` should instead return this value as a `formsets` item in the dict returned from `get_form_options`
+ * Panels that define `widget_overrides` should instead return this value as a `widgets` item in the dict returned from `get_form_options`
+
+The template context for panels derived from `BaseChooserPanel` has changed. `BaseChooserPanel` is deprecated and now functionally identical to `FieldPanel`; as a result, the context variable `is_chosen`, and the variable name given by the panel's `object_type_name` property, are no longer available on the template. The only available variables are now `field` and `show_add_comment_button`. If your template depends on these additional variables, you will need to pass them explicitly by overriding the `render_as_field` method.
 
 ### ModelAdmin forms must subclass `WagtailAdminModelForm`
 
@@ -134,7 +146,3 @@ When overriding the `get_form_class` method of a ModelAdmin `CreateView` or `Edi
 
 -   The `size` argument was used to add a `length` parameter to the HTTP header.
 -   This was never part of the HTTP/1.0 and HTTP/1.1 specifications see [RFC7232](https://httpwg.org/specs/rfc7232.html#header.if-modified-since) and existed only as a an unofficial implementation in IE browsers.
-
-### Base EditHandler classes renamed
-
-The base `wagtail.admin.edit_handlers.EditHandler` class can now be found at `wagtail.admin.panels.Panel`, and `wagtail.admin.edit_handlers.BaseCompositeEditHandler` can now be found at `wagtail.admin.panels.PanelGroup`. Additionally, templates previously located under `wagtailadmin/edit_handlers/` can now be found at `wagtailadmin/panels/`, and `wagtailforms/edit_handlers/form_responses_panel.html` is now at `wagtailforms/panels/form_responses_pane.html`.