[5.1.x] Fixed #22828 -- Warned that ModelAdmin get hooks return the property itself rather a copy.

Backport of b8e9cdf13b7ab6621926a5d2aad3e2bb745aae00 from main.

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index c2061f11ab..4a8b52c18f 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1473,6 +1473,27 @@ templates used by the :class:`ModelAdmin` views:
 
     See also :ref:`saving-objects-in-the-formset`.
 
+.. warning::
+
+    All hooks that return a ``ModelAdmin`` property return the property itself
+    rather than a copy of its value. Dynamically modifying the value can lead
+    to surprising results.
+
+    Let's take :meth:`ModelAdmin.get_readonly_fields` as an example::
+
+        class PersonAdmin(admin.ModelAdmin):
+            readonly_fields = ["name"]
+
+            def get_readonly_fields(self, request, obj=None):
+                readonly = super().get_readonly_fields(request, obj)
+                if not request.user.is_superuser:
+                    readonly.append("age")  # Edits the class attribute.
+                return readonly
+
+    This results in ``readonly_fields`` becoming
+    ``["name", "age", "age", ...]``, even for a superuser, as ``"age"`` is added
+    each time non-superuser visits the page.
+
 .. method:: ModelAdmin.get_ordering(request)
 
     The ``get_ordering`` method takes a ``request`` as parameter and