Bad things happen if you name your custom user app "auth"

[Charlie DeTar]

It seems that odd conflicts and unexpected behavior happen if you create an app specifying a custom user model and name that app "auth"[1]. The general principle might also apply that bad things happen when you include two apps with the same ultimate module name (e.g. both "<foo>" and "django.contrib.<foo>", as well as any other dotted path to an app).

The documentation for reusable apps ​https://docs.djangoproject.com/en/dev/intro/reusable-apps/ mentions choosing app names that don't conflict with existing published apps for sharing convenience, but I can't find any mention of the fact that module names (even with differing dotted prefixes) should never collide for purposes of proper code function. Particularly with custom user models, where bare "auth" is a very natural thing to name your own implementation, this seems worth a mention.

[1] Specific problems: importing the model in the shell (e.g. "import auth.models.User") resulted in importing a "django.contrib.auth.models.User"; the post-syncdb signal for creating the first superuser followed the contract for creating a django.contrib User but put the results in a table made for the custom User, and trying to register the custom User resulted in an "already registered" error.

[alasdair]

The warning for the ​INSTALLED_APPS setting covers this.

> App names must be unique

The application names (that is, the final dotted part of the path to the module containing models.py) defined in INSTALLED_APPS must be unique. For example, you can’t include both django.contrib.auth and myproject.auth in INSTALLED_APPS.

I suggest we add a similar warning to the re-usable app tutorial. A reusable app shouldn't be named auth, messages, sites, or any other contrib name, or it's going to cause problems.

Allowing multiple installed apps with the same name is already covered by the app refactor #3591. I'm marking the ticket as accepted because I think we can improve the reusable-apps tutorial.

[alasdair]

Pull request with suggested addition to the reusable apps tutorial: ​https://github.com/django/django/pull/2032

[Tim Graham <timograham@…>]

In 317fd13c7ac25db94d3dabf8ee115acbfbd3e5a7:

Fixed #21562 -- Warned against using the same app name as a django contrib app.

Thanks yourcelf for the report.

[Tim Graham <timograham@…>]

In 4f9590836ca679e4aef2627a71f4277ca4c80605:

[1.6.x] Fixed #21562 -- Warned against using the same app name as a django contrib app.

Thanks yourcelf for the report.

Backport of 317fd13c7a from master