[1.8.x] Fixed #24690 -- Added a warning about mutable defaults for ArrayField.

Backport of f93e7f5674436b230e6b4023570939a20c0c6055 from master

1 files changed, 6 insertions, 0 deletions

diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt
index 3d36018893..fb9ed14fd9 100644
--- a/docs/ref/contrib/postgres/fields.txt
+++ b/docs/ref/contrib/postgres/fields.txt
@@ -17,6 +17,12 @@ ArrayField
     <ArrayField.size>`. ``ArrayField`` can be nested to store multi-dimensional
     arrays.
 
+    If you give the field a :attr:`~django.db.models.Field.default`, ensure
+    it's a callable such as ``list`` (for an empty default) or a callable that
+    returns a list (such as a function). Incorrectly using ``default=[]``
+    creates a mutable default that is shared between all instances of
+    ``ArrayField``.
+
     .. attribute:: base_field
 
         This is a required argument.