Refs #32339 -- Deprecated default.html form template.

Co-authored-by: Carlton Gibson <carlton.gibson@noumenal.es>

3 files changed, 98 insertions, 0 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index bb6b889f91..73ed9a3c6b 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -105,6 +105,9 @@ details on these changes.
 
 * The ``django.contrib.auth.hashers.CryptPasswordHasher`` will be removed.
 
+* The ``"django/forms/default.html"`` and
+  ``"django/forms/formsets/default.html"`` templates will be removed.
+
 * The ability to pass ``nulls_first=False`` or ``nulls_last=False`` to
   ``Expression.asc()`` and ``Expression.desc()`` methods, and the ``OrderBy``
   expression will be removed.
diff --git a/docs/ref/forms/renderers.txt b/docs/ref/forms/renderers.txt
index 8c0263e051..f11b23ab12 100644
--- a/docs/ref/forms/renderers.txt
+++ b/docs/ref/forms/renderers.txt
@@ -56,6 +56,12 @@ should return a rendered templates (as a string) or raise
         Defaults to ``"django/forms/default.html"``, which is a proxy for
         ``"django/forms/table.html"``.
 
+        .. deprecated:: 4.1
+
+        The ``"django/forms/default.html"`` template is deprecated and will be
+        removed in Django 5.0. The default will become
+        ``"django/forms/default.html"`` at that time.
+
     .. attribute:: formset_template_name
 
         .. versionadded:: 4.1
@@ -65,6 +71,12 @@ should return a rendered templates (as a string) or raise
         Defaults to ``"django/forms/formsets/default.html"``, which is a proxy
         for ``"django/forms/formsets/table.html"``.
 
+        .. deprecated:: 4.1
+
+        The ``"django/forms/formset/default.html"`` template is deprecated and
+        will be removed in Django 5.0. The default will become
+        ``"django/forms/formset/div.html"`` template.
+
     .. method:: get_template(template_name)
 
         Subclasses must implement this method with the appropriate template
@@ -97,6 +109,26 @@ If you want to render templates with customizations from your
 :setting:`TEMPLATES` setting, such as context processors for example, use the
 :class:`TemplatesSetting` renderer.
 
+.. class:: DjangoDivFormRenderer
+
+.. versionadded:: 4.1
+
+Subclass of :class:`DjangoTemplates` that specifies
+:attr:`~BaseRenderer.form_template_name` and
+:attr:`~BaseRenderer.formset_template_name` as ``"django/forms/div.html"`` and
+``"django/forms/formset/div.html"`` respectively.
+
+This is a transitional renderer for opt-in to the new ``<div>`` based
+templates, which are the default from Django 5.0.
+
+Apply this via the :setting:`FORM_RENDERER` setting::
+
+    FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
+
+Once the ``<div>`` templates are the default, this transitional renderer will
+be deprecated, for removal in Django 6.0. The ``FORM_RENDERER`` declaration can
+be removed at that time.
+
 ``Jinja2``
 ----------
 
@@ -113,6 +145,17 @@ templates for widgets that don't have any, you can't use this renderer. For
 example, :mod:`django.contrib.admin` doesn't include Jinja2 templates for its
 widgets due to their usage of Django template tags.
 
+.. class:: Jinja2DivFormRenderer
+
+.. versionadded:: 4.1
+
+A transitional renderer as per :class:`DjangoDivFormRenderer` above, but
+subclassing :class:`Jinja2` for use with the Jinja2 backend.
+
+Apply this via the :setting:`FORM_RENDERER` setting::
+
+    FORM_RENDERER = "django.forms.renderers.Jinja2DivFormRenderer"
+
 ``TemplatesSetting``
 --------------------
 
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index 36a510b460..49f74a93b3 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -74,6 +74,24 @@ Validation of Constraints
 in the :attr:`Meta.constraints <django.db.models.Options.constraints>` option
 are now checked during :ref:`model validation <validating-objects>`.
 
+Form rendering accessibility
+----------------------------
+
+In order to aid users with screen readers, and other assistive technology, new
+``<div>`` based form templates are available from this release. These provide
+more accessible navigation than the older templates, and are able to correctly
+group related controls, such as radio-lists, into fieldsets.
+
+The new templates are recommended, and will become the default form rendering
+style when outputting a form, like ``{{ form }}`` in a template, from Django
+5.0.
+
+In order to ease adopting the new output style, the default form and formset
+templates are now configurable at the project level via the
+:setting:`FORM_RENDERER` setting.
+
+See :ref:`the Forms section (below)<forms-4.1>` for full details.
+
 .. _csrf-cookie-masked-usage:
 
 ``CSRF_COOKIE_MASKED`` setting
@@ -253,6 +271,8 @@ File Uploads
 
 * ...
 
+.. _forms-4.1:
+
 Forms
 ~~~~~
 
@@ -279,6 +299,34 @@ Forms
   as the template implements ``<fieldset>`` and ``<legend>`` to group related
   inputs and is easier for screen reader users to navigate.
 
+  The div-based output will become the default rendering style from Django 5.0.
+
+* In order to smooth adoption of the new ``<div>`` output style, two
+  transitional form renderer classes are available:
+  :class:`django.forms.renderers.DjangoDivFormRenderer` and
+  :class:`django.forms.renderers.Jinja2DivFormRenderer`, for the Django and
+  Jinja2 template backends respectively.
+
+  You can apply one of these via the :setting:`FORM_RENDERER` setting. For
+  example::
+
+    FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"
+
+  Once the ``<div>`` output style is the default, from Django 5.0, these
+  transitional renderers will be deprecated, for removal in Django 6.0. The
+  ``FORM_RENDERER`` declaration can be removed at that time.
+
+* If the new ``<div>`` output style is not appropriate for your project, you should
+  define a renderer subclass specifying
+  :attr:`~django.forms.renderers.BaseRenderer.form_template_name` and
+  :attr:`~django.forms.renderers.BaseRenderer.formset_template_name` for your
+  required style, and set :setting:`FORM_RENDERER` accordingly.
+
+  For example, for the ``<p>`` output style used by :meth:`~.Form.as_p`, you
+  would define a form renderer setting ``form_template_name`` to
+  ``"django/forms/p.html"`` and ``formset_template_name`` to
+  ``"django/forms/formsets/p.html"``.
+
 * The new :meth:`~django.forms.BoundField.legend_tag` allows rendering field
   labels in ``<legend>`` tags via the new ``tag`` argument of
   :meth:`~django.forms.BoundField.label_tag`.
@@ -718,6 +766,10 @@ Miscellaneous
   ``Expression.asc()`` and ``Expression.desc()`` methods, and the ``OrderBy``
   expression is deprecated. Use ``None`` instead.
 
+* The ``"django/forms/default.html"`` and
+  ``"django/forms/formsets/default.html"`` templates which are a proxy to the
+  table-based templates are deprecated. Use the specific template instead.
+
 Features removed in 4.1
 =======================