Document custom field subclass change requires new custom field class

[Baylee Feore]

Related to #26586

Can't alter a custom field to have a different base field type. Documentation should be updated to reflect this and proposed solution.

Example before state:

class CustomCharField(models.CharField):
    def foo(self):
        pass

class Author(models.Model):
    name = CustomCharField(max_length=255)

Example of what won't work:

class CustomCharField(models.TextField):
    def foo(self):
        pass

class Author(models.Model):
    name = CustomCharField(max_length=255)

Example of what you should change to:

class CustomFieldMixin(object):
    def foo(self):
        pass

class CustomCharField(CustomFieldMixin, models.CharField):
    pass

class CustomTextField(CustomFieldMixin, models.TextField):
    pass

class Author(models.Model):
    name = CustomTextField(max_length=255)

Should also include link to: ​https://docs.djangoproject.com/en/1.9/topics/migrations/#considerations-when-removing-model-fields to explain why user must keep old field definition around.

[Phil Krylov]

The method/mixin part is confusing for an average reader who is searching for a simple case; I think that it should be an example separate from the original case in #26586 where no mixin is needed.

[Tim Graham]

​PR. I haven't reviewed it myself, but marking as needs improvement per previous comment.

[Baylee Feore]

That makes sense. I've updated the PR to use a simplified example.

[Philip James]

This doc patch is clear and concise, doesn't cover anything extraneous, and seems to meet all the docs guidelines.

[Tim Graham <timograham@…>]

In 7767978b:

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

[Tim Graham <timograham@…>]

In 4765769b:

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

Backport of 7767978beec6098baea75d50a191a3b8224e729f from master

[Tim Graham <timograham@…>]

In 5e46075:

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

Backport of 7767978beec6098baea75d50a191a3b8224e729f from master