[1.7.x] Improve docs around deconstruction/serialisation (refs #22337)

docs/howto/custom-file-storage.txt

@@ -34,6 +34,13 @@ You'll need to follow these steps:
    In addition, if your class provides local file storage, it must override
    the ``path()`` method.
 
+#. Your storage class must be :ref:`deconstructible <custom-deconstruct-method>`
+   so it can be serialized when it's used on a field in a migration. As long
+   as your field has arguments that are themselves
+   :ref:`serializable <migration-serializing>`, you can use the
+   ``django.utils.deconstruct.deconstructible`` class decorator for this
+   (that's what Django uses on FileSystemStorage).
+
 Your custom storage system may override any of the storage methods explained in
 :doc:`/ref/files/storage`, but you **must** implement the following methods:
 

docs/releases/1.7.txt

@@ -128,6 +128,11 @@ built-in Django fields (``django/db/models/fields/__init__.py``) as several
 fields, including ``DecimalField`` and ``DateField``, override it and show how
 to call the method on the superclass and simply add or remove extra arguments.
 
+This also means that all arguments to fields must themselves be serializable;
+to see what we consider serializable, and to find out how to make your own
+classes serializable, read the
+:ref:`migration serialization documentation <migration-serializing>`.
+
 Calling custom ``QuerySet`` methods from the ``Manager``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -876,6 +881,22 @@ Instead, you are encouraged to load initial data in migrations if you need it
 this has the added advantage that your initial data will not need updating
 every time you change the schema.
 
+deconstruct() and serializability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django now requires all Field classes and all of their constructor arguments
+to be serializable. If you modify the constructor signature in your custom
+Field in any way, you'll need to implement a deconstruct() method;
+we've expanded the custom field documentation with :ref:`instructions
+on implementing this method <custom-field-deconstruct-method>`.
+
+The requirement for all field arguments to be
+:ref:`serializable <migration-serializing>` means that any custom class
+instances being passed into Field constructors - things like custom Storage
+subclasses, for instance - need to have a :ref:`deconstruct method defined on
+them as well <custom-deconstruct-method>`, though Django provides a handy
+class decorator that will work for most applications.
+
 App-loading changes
 ~~~~~~~~~~~~~~~~~~~
 

docs/topics/migrations.txt

@@ -520,6 +520,22 @@ available at the top level of a module it is not serializable.
 Django will write out the value as an instantiation of your class with the
 given arguments, similar to the way it writes out references to Django fields.
 
+As long as all of the arguments to your class' constructor are themselves
+serializable, you can just use the ``@deconstructible`` class decorator
+from ``django.utils.deconstruct`` to add the method::
+
+    from django.utils.deconstruct import deconstructible
+
+    @deconstructible
+    class MyCustomClass(object):
+
+        def __init__(self, foo=1):
+            ...
+
+The decorator adds logic to capture and preserve the arguments on their
+way into your constructor, and then returns those arguments exactly when
+deconstruct() is called.
+
 Upgrading from South
 --------------------