[1.10.x] Fixed #26702 -- Documented how to change the base class of a custom field.

Backport of 7767978beec6098baea75d50a191a3b8224e729f from master

1 files changed, 28 insertions, 0 deletions

diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index 1730419787..0c26d2ca5d 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -311,6 +311,34 @@ and reconstructing the field::
     new_instance = MyField(*args, **kwargs)
     self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)
 
+Changing a custom field's base class
+------------------------------------
+
+You can't change the base class of a custom field because Django won't detect
+the change and make a migration for it. For example, if you start with::
+
+    class CustomCharField(models.CharField):
+        ...
+
+and then decide that you want to use ``TextField`` instead, you can't change
+the subclass like this::
+
+    class CustomCharField(models.TextField):
+        ...
+
+Instead, you must create a new custom field class and update your models to
+reference it::
+
+    class CustomCharField(models.CharField):
+        ...
+
+    class CustomTextField(models.TextField):
+        ...
+
+As discussed in :ref:`removing fields <migrations-removing-model-fields>`, you
+must retain the original ``CustomCharField`` class as long as you have
+migrations that reference it.
+
 Documenting your custom field
 -----------------------------