Admonitions in custom User model documentation may be scaring off users
|Reported by:||Russell Keith-Magee||Owned by:||Keith Edmiston|
|Has patch:||no||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
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:
- "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...."
- "One limitation of custom User models is that installing a custom User model will break any proxy model extending User. ..."
- "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.