Clarify UserViewSet customization to avoid confusion with the custom user model's app config

docs/advanced_topics/customisation/custom_user_models.md

@@ -41,13 +41,21 @@ from myapp.models import MembershipStatus
 
 
 class CustomUserEditForm(UserEditForm):
-    country = forms.CharField(required=True, label=_("Country"))
     status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
 
+    # Use ModelForm's automatic form fields generation for the model's `country` field,
+    # but use an explicit custom form field for `status`.
+    class Meta(UserEditForm.Meta):
+        fields = UserEditForm.Meta.fields | {"country", "status"}
+
 
 class CustomUserCreationForm(UserCreationForm):
-    country = forms.CharField(required=True, label=_("Country"))
     status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
+
+    # Use ModelForm's automatic form fields generation for the model's `country` field,
+    # but use an explicit custom form field for `status`.
+    class Meta(UserCreationForm.Meta):
+        fields = UserCreationForm.Meta.fields | {"country", "status"}
 ```
 
 ## Extending the create and edit templates
@@ -123,13 +131,18 @@ Replace `wagtail.users` in `settings.INSTALLED_APPS` with the path to `CustomUse
 ```python
 INSTALLED_APPS = [
     ...,
+    # Make sure you have two separate entries for the following:
     "myapp",  # an app that contains the custom user model
     "myproject.apps.CustomUsersAppConfig",  # a custom app config for the wagtail.users app
-    # "wagtail.users",
+    # "wagtail.users",  # this should be removed in favour of the custom app config
     ...,
 ]
 ```
 
+```{warning}
+You can also place the `WagtailUsersAppConfig` subclass inside the same `apps.py` file of your custom user model's app (instead of in a `myproject/apps.py` file), but you need to be careful. Make sure to use two separate config classes instead of turning your existing `AppConfig` subclass into a `WagtailUsersAppConfig` subclass, as that would cause Django to pick up your custom user model as being part of `wagtail.users`. You may also need to set {attr}`~django.apps.AppConfig.default` to `True` in your own app's `AppConfig`, unless you already use a dotted path to the app's `AppConfig` subclass in `INSTALLED_APPS`.
+```
+
 The `UserViewSet` class is a subclass of {class}`~wagtail.admin.viewsets.model.ModelViewSet` and thus it supports most of [the customizations available for `ModelViewSet`](generic_views). For example, you can use a custom directory for the templates by setting {attr}`~wagtail.admin.viewsets.model.ModelViewSet.template_prefix`:
 
 ```py

docs/releases/6.2.md

@@ -214,7 +214,7 @@ And the following settings:
 ```py
 WAGTAIL_USER_EDIT_FORM = "myapp.forms.CustomUserEditForm"
 WAGTAIL_USER_CREATION_FORM = "myapp.forms.CustomUserCreationForm"
-WAGTAIL_USER_CUSTOM_FIELDS = ["country"]
+WAGTAIL_USER_CUSTOM_FIELDS = ["country", "status"]
 ```
 
 #### After
@@ -225,22 +225,20 @@ Change the custom forms to the following:
 class CustomUserEditForm(UserEditForm):
     status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
 
-    # Use ModelForm's automatic form fields generation for the model's `country` field.
-    # Alternatively, you can also define a `country` form field directly on
-    # `CustomUserEditForm` along with any desired options for the field, and skip
-    # the following custom Meta subclass.
+    # Use ModelForm's automatic form fields generation for the model's `country` field,
+    # but use an explicit custom form field for `status`.
+    # This replaces the `WAGTAIL_USER_CUSTOM_FIELDS` setting.
     class Meta(UserEditForm.Meta):
-        fields = UserEditForm.Meta.fields | {"country"}
+        fields = UserEditForm.Meta.fields | {"country", "status"}
 
 class CustomUserCreationForm(UserCreationForm):
     status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
 
-    # Use ModelForm's automatic form fields generation for the model's `country` field.
-    # Alternatively, you can also define a `country` form field directly on
-    # `CustomUserCreationForm` along with any desired options for the field, and skip
-    # the following custom Meta subclass.
+    # Use ModelForm's automatic form fields generation for the model's `country` field,
+    # but use an explicit custom form field for `status`.
+    # This replaces the `WAGTAIL_USER_CUSTOM_FIELDS` setting.
     class Meta(UserCreationForm.Meta):
-        fields = UserEditForm.Meta.fields | {"country"}
+        fields = UserEditForm.Meta.fields | {"country", "status"}
 ```
 
 Create a custom `UserViewSet` subclass in e.g. `myapp/viewsets.py`:
@@ -253,16 +251,17 @@ from .forms import CustomUserCreationForm, CustomUserEditForm
 
 
 class UserViewSet(WagtailUserViewSet):
+    # This replaces the WAGTAIL_USER_EDIT_FORM and WAGTAIL_USER_CREATION_FORM settings
     def get_form_class(self, for_update=False):
         if for_update:
             return CustomUserEditForm
         return CustomUserCreationForm
 ```
 
-Create a custom `WagtailUsersAppConfig` subclass in e.g. `myapp/apps.py` (or reuse the same class if you have a custom `GroupViewSet` as described in [](customizing_group_views)). Then, set a `user_viewset` attribute pointing to the custom `UserViewSet` subclass:
+If you already have a custom `GroupViewSet` as described in [](customizing_group_views), you can reuse the custom `WagtailUsersAppConfig` subclass. Otherwise, create an `apps.py` file within your project folder (the one containing the top-level settings and urls modules) e.g. `myproject/apps.py`. Then, create a custom `WagtailUsersAppConfig` subclass in that file, with a `user_viewset` attribute pointing to the custom `UserViewSet` subclass:
 
 ```py
-# myapp/apps.py
+# myproject/apps.py
 from wagtail.users.apps import WagtailUsersAppConfig
 
 
@@ -277,12 +276,19 @@ Replace `wagtail.users` in `settings.INSTALLED_APPS` with the path to `CustomUse
 ```python
 INSTALLED_APPS = [
     ...,
-    "myapp.apps.CustomUsersAppConfig",
-    # "wagtail.users",
+    # Make sure you have two separate entries for the custom user model's app
+    # and the custom app config for the wagtail.users app
+    "myapp",  # an app that contains the custom user model
+    "myproject.apps.CustomUsersAppConfig",  # a custom app config for the wagtail.users app
+    # "wagtail.users",  # this should be removed in favour of the custom app config
     ...,
 ]
 ```
 
+```{warning}
+You can also place the `WagtailUsersAppConfig` subclass inside the same `apps.py` file of your custom user model's app (instead of in a `myproject/apps.py` file), but you need to be careful. Make sure to use two separate config classes instead of turning your existing `AppConfig` subclass into a `WagtailUsersAppConfig` subclass, as that would cause Django to pick up your custom user model as being part of `wagtail.users`. You may also need to set {attr}`~django.apps.AppConfig.default` to `True` in your own app's `AppConfig`, unless you already use a dotted path to the app's `AppConfig` subclass in `INSTALLED_APPS`.
+```
+
 For more details, see [](custom_userviewset).
 
 ## Upgrade considerations - changes affecting Wagtail customisations