Refs #24487 -- Added upgrade tips about removal of SortedDict.

Thanks Pascal Chambon for the initial patch.

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 72e8bbe4c7..f00e7bd715 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -1512,6 +1512,22 @@ Python versions, this module isn't useful anymore. It has been deprecated. Use
 As :class:`~collections.OrderedDict` was added to the standard library in
 Python 2.7, ``SortedDict`` is no longer needed and has been deprecated.
 
+The two additional, deprecated methods provided by ``SortedDict`` (``insert()``
+and ``value_for_index()``) have been removed. If you relied on these methods to
+alter structures like form fields, you should now treat these ``OrderedDict``\s
+as immutable objects and override them to change their content.
+
+For example, you might want to override ``MyFormClass.base_fields`` (although
+this attribute isn't considered a public API) to change the ordering of fields
+for all ``MyFormClass`` instances; or similarly, you could override
+``self.fields`` from inside ``MyFormClass.__init__()``, to change the fields
+for a particular form instance. For example (from Django itself)::
+
+    PasswordChangeForm.base_fields = OrderedDict(
+        (k, PasswordChangeForm.base_fields[k])
+        for k in ['old_password', 'new_password1', 'new_password2']
+    )
+
 Custom SQL location for models package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~