Refs #32013 -- Added backward incompatibility note about ModelChoiceIterator changes.

2 files changed, 11 insertions, 1 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index fb6c14595c..e5a9c8f880 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1439,7 +1439,9 @@ customize the yielded 2-tuple choices.
 
             In older versions, the first ``value`` element in the choice tuple
             is the ``field`` value itself, rather than a
-            ``ModelChoiceIteratorValue`` instance.
+            ``ModelChoiceIteratorValue`` instance. In most cases this proxies
+            transparently but, if you need the ``field`` value itself, use the
+            :attr:`ModelChoiceIteratorValue.value` attribute instead.
 
 ``ModelChoiceIteratorValue``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/releases/3.1.txt b/docs/releases/3.1.txt
index a9ebe7b094..b723d0c566 100644
--- a/docs/releases/3.1.txt
+++ b/docs/releases/3.1.txt
@@ -724,6 +724,14 @@ Miscellaneous
   without the ``type`` attribute to follow `WHATWG recommendations
   <https://html.spec.whatwg.org/multipage/scripting.html#the-script-element>`_.
 
+* :class:`~django.forms.ModelChoiceIterator`, used by
+  :class:`~django.forms.ModelChoiceField` and
+  :class:`~django.forms.ModelMultipleChoiceField`, now yields 2-tuple choices
+  containing :class:`~django.forms.ModelChoiceIteratorValue` instances as the
+  first ``value`` element in each choice. In most cases this proxies
+  transparently, but if you need the ``field`` value itself, use the
+  :attr:`.ModelChoiceIteratorValue.value` attribute instead.
+
 .. _deprecated-features-3.1:
 
 Features deprecated in 3.1