Add upgrade consideration note for third-party packages implementing their own panels

docs/releases/2.17.md

@@ -66,6 +66,12 @@ Here are other changes related to the redesign:
 * 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.
 
-### Template context for `BaseChooserPanel`
+### Phasing-out of special-purpose field panel types
 
-`BaseChooserPanel` no longer passes the context variable `is_chosen`, or the variable name given by the panel's `object_type_name` property, to the panel's template. The only available variables are now `field` and `show_add_comment_button`. If you have subclassed `BaseChooserPanel` and provided a custom template (via the `field_template` attribute) that depends on additional context variables, you will need to pass them explicitly by overriding the `render_as_field` method.
+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:
+
+ * 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 - 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.