Refs #29738 -- Allowed registering serializers with MigrationWriter.

2 files changed, 32 insertions, 0 deletions

diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 87a7ef4931..c371d50281 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -211,6 +211,9 @@ Migrations
 
 * ``NoneType`` can now be serialized in migrations.
 
+* You can now :ref:`register custom serializers <custom-migration-serializers>`
+  for migrations.
+
 Models
 ~~~~~~
 
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
index b44f78cc69..2f33b97878 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -697,6 +697,35 @@ Django cannot serialize:
 - Arbitrary class instances (e.g. ``MyClass(4.3, 5.7)``)
 - Lambdas
 
+.. _custom-migration-serializers:
+
+Custom serializers
+------------------
+
+.. versionadded:: 2.2
+
+You can serialize other types by writing a custom serializer. For example, if
+Django didn't serialize :class:`~decimal.Decimal` by default, you could do
+this::
+
+    from decimal import Decimal
+
+    from django.db.migrations.serializer import BaseSerializer
+    from django.db.migrations.writer import MigrationWriter
+
+    class DecimalSerializer(BaseSerializer):
+        def serialize(self):
+            return repr(self.value), {'from decimal import Decimal'}
+
+    MigrationWriter.register_serializer(Decimal, DecimalSerializer)
+
+The first argument of ``MigrationWriter.register_serializer()`` is a type or
+iterable of types that should use the serializer.
+
+The ``serialize()`` method of your serializer must return a string of how the
+value should appear in migrations and a set of any imports that are needed in
+the migration.
+
 .. _custom-deconstruct-method:
 
 Adding a ``deconstruct()`` method