[2.2.x] Fixed #28667 -- Clarified how to override list of forms fields for custom UserAdmin with a custom user model.

Backport of c13e3715f5f46f2ee4ddba357e2589a45e831813 from master

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index fd723cbb94..ce4c1c9edf 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -877,6 +877,28 @@ override any of the definitions that refer to fields on
 ``django.contrib.auth.models.AbstractUser`` that aren't on your
 custom user class.
 
+.. note::
+
+    If you are using a custom ``ModelAdmin`` which is a subclass of
+    ``django.contrib.auth.admin.UserAdmin``, then you need to add your custom
+    fields to ``fieldsets`` (for fields to be used in editing users) and to
+    ``add_fieldsets`` (for fields to be used when creating a user). For
+    example::
+
+        from django.contrib.auth.admin import UserAdmin
+
+        class CustomUserAdmin(UserAdmin):
+            ...
+            fieldsets = UserAdmin.fieldsets + (
+                (None, {'fields': ('custom_field',)}),
+            )
+            add_fieldsets = UserAdmin.add_fieldsets + (
+                (None, {'fields': ('custom_field',)}),
+            )
+
+    See :ref:`a full example <custom-users-admin-full-example>` for more
+    details.
+
 Custom users and permissions
 ----------------------------
 
@@ -962,6 +984,8 @@ If your project uses proxy models, you must either modify the proxy to extend
 the user model that's in use in your project, or merge your proxy's behavior
 into your :class:`~django.contrib.auth.models.User` subclass.
 
+.. _custom-users-admin-full-example:
+
 A full example
 --------------