[1.10.x] Fixed #24370 -- Recommended starting with a custom user model.

Backport of d02a03d574b6623ce0d648dd676ae278d46375fb from master

1 files changed, 49 insertions, 36 deletions

diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index 56db14fc56..398513d948 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -385,42 +385,55 @@ This dotted pair describes the name of the Django app (which must be in your
 :setting:`INSTALLED_APPS`), and the name of the Django model that you wish to
 use as your User model.
 
-.. warning::
-
-   Changing :setting:`AUTH_USER_MODEL` has a big effect on your database
-   structure. It changes the tables that are available, and it will affect the
-   construction of foreign keys and many-to-many relationships. If you intend
-   to set :setting:`AUTH_USER_MODEL`, you should set it before creating
-   any migrations or running ``manage.py migrate`` for the first time.
-
-   Changing this setting after you have tables created is not supported
-   by :djadmin:`makemigrations` and will result in you having to manually
-   fix your schema, port your data from the old user table, and possibly
-   manually reapply some migrations.
-
-.. warning::
-
-   Due to limitations of Django's dynamic dependency feature for swappable
-   models, you must ensure that the model referenced by :setting:`AUTH_USER_MODEL`
-   is created in the first migration of its app (usually called ``0001_initial``);
-   otherwise, you will have dependency issues.
-
-   In addition, you may run into a CircularDependencyError when running your
-   migrations as Django won't be able to automatically break the dependency
-   loop due to the dynamic dependency. If you see this error, you should
-   break the loop by moving the models depended on by your User model
-   into a second migration (you can try making two normal models that
-   have a ForeignKey to each other and seeing how ``makemigrations`` resolves that
-   circular dependency if you want to see how it's usually done)
-
-.. admonition:: Reusable apps and ``AUTH_USER_MODEL``
-
-   Reusable apps shouldn't implement a custom user model. A project may use
-   many apps, and two reusable apps that implemented a custom user model
-   couldn't be used together. If you need to store per user information in your
-   app, use a :class:`~django.db.models.ForeignKey` or
-   :class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL``
-   as described below.
+Using a custom user model when starting a project
+-------------------------------------------------
+
+If you're starting a new project, it's highly recommended to set up a custom
+user model, even if the default :class:`~django.contrib.auth.models.User` model
+is sufficient for you. This model behaves identically to the default user
+model, but you'll be able to customize it in the future if the need arises::
+
+    from django.conf.auth.models import AbstractUser
+
+    class User(AbstractUser):
+        pass
+
+Don't forget to point :setting:`AUTH_USER_MODEL` to it. Do this before creating
+any migrations or running ``manage.py migrate`` for the first time.
+
+Changing to a custom user model mid-project
+-------------------------------------------
+
+Changing :setting:`AUTH_USER_MODEL` after you've created database tables is
+significantly more difficult since it affects foreign keys and many-to-many
+relationships, for example.
+
+This change can't be done automatically and requires manually fixing your
+schema, moving your data from the old user table, and possibly manually
+reapplying some migrations. See :ticket:`25313` for an outline of the steps.
+
+Due to limitations of Django's dynamic dependency feature for swappable
+models, the model referenced by :setting:`AUTH_USER_MODEL` must be created in
+the first migration of its app (usually called ``0001_initial``); otherwise,
+you'll have dependency issues.
+
+In addition, you may run into a ``CircularDependencyError`` when running your
+migrations as Django won't be able to automatically break the dependency loop
+due to the dynamic dependency. If you see this error, you should break the loop
+by moving the models depended on by your user model into a second migration.
+(You can try making two normal models that have a ``ForeignKey`` to each other
+and seeing how ``makemigrations`` resolves that circular dependency if you want
+to see how it's usually done.)
+
+Reusable apps and ``AUTH_USER_MODEL``
+-------------------------------------
+
+Reusable apps shouldn't implement a custom user model. A project may use many
+apps, and two reusable apps that implemented a custom user model couldn't be
+used together. If you need to store per user information in your app, use
+a :class:`~django.db.models.ForeignKey` or
+:class:`~django.db.models.OneToOneField` to ``settings.AUTH_USER_MODEL``
+as described below.
 
 Referencing the ``User`` model
 ------------------------------