Admonitions in custom User model documentation may be scaring off users

[Russell Keith-Magee]

​Evan Stone on django-users indicated that he was initially hesitant to use custom User models because the documentation made it sound like it was going to be painful. Specifically, he identified the following pieces of documentation:

1. "Think carefully before handling information not directly related to authentication in your custom User Model."

2. "It may be better to store app-specific user information in a model that has a relation with the User model. That allows each app to specify its own user data requirements without risking conflicts with other apps...."

3. "One limitation of custom User models is that installing a custom User model will break any proxy model extending User. ..."

and

4. "Another limitation of custom User models is that you can’t use django.contrib.auth.get_user_model() as the sender or target of "

Points 1 and 2 are asking users to consider an architectural question -- do you need a custom user model at all? If you actually *are* using a username-based login system, and you just want to track some extra information about the user, the right approach may *not* be to create a custom user model.

Points 3 and 4 are pointing out known limitations. Proxy models are a problem because they use subclassing, and they will be subclassing the wrong class; signals are a problem because at the point the signal is registered, there's no guarantee that the User model has been correctly defined. There's not much we can do about (3); (4) is something that should get cleaned up when we eventually land app refactor.

The points made by the documentation are all valid, but could perhaps be made in less threatening or alarmist tones, or clarified so that they don't seem like such big problems.

[Keith Edmiston]

Considering modification of the admonition section in the docs...from this:

Model design considerations

Think carefully before handling information not directly related to authentication in your custom User Model.

It may be better to store app-specific user information in a model that has a relation with the User model. That allows each app to specify its own user data requirements without risking conflicts with other apps. On the other hand, queries to retrieve this related information will involve a database join, which may have an effect on performance.

to this:

Model design considerations

A point to think about in your design/decision is whether you need a custom user model at all?

Before choosing to handle information not directly related to authentication in your custom User Model, consider that it may be a better choice to store app-specific user information in a model that has a relation with the User model. This approach allows each app to specify its own user data requirements without risking conflicts with other apps. Keep in mind that queries to retrieve this related information will involve a database join, which may have an effect on performance.

---

Let me know your thoughts and I'll make a pull request.

[Russell Keith-Magee]

Looks like a good update to cover the first point, but points 2-4 are still relevant.

[Keith Edmiston]

Replying to russellm:

Looks like a good update to cover the first point, but points 2-4 are still relevant.

I'm a bit confused then. I felt like the above suggestion "softened the edges" a bit for 1 & 2 both. Perhaps you can be more explicit about what it should look like in accommodating #2?

Reading your initial report above, I took it to mean that #3 wasn't something we could really do anything about here and #4 was more of a fix that will come in a later version.

Can you help me better understand how to change this to address all 4 points?

[Tobias Kunze]

The fourth warning is no longer part of the docs. The third warning is still there, but I don't think it sounds alarmist or needs to be rephrased. I rephrased the admonition at the beginning of the custom user model implementation docs by putting the advantages first and the potential benefits of related models second.

[Mariusz Felisiak <felisiak.mariusz@…>]

In eb16c726:

Fixed #20629 -- Rephrased custom user models admonition.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 54fcdf1:

[2.2.x] Fixed #20629 -- Rephrased custom user models admonition.

Backport of eb16c7260e573ec513d84cb586d96bdf508f3173 from master