[Django] #24370: Recommend that all new projects use a custom user model
Django
------------------------------------------------+------------------------
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
Right now, our custom user model docs are buried deep in the auth-
customization docs, and are a bit intimidating - because it assumes that
you would only need a custom user model if making significant departures
from the default User, the examples used require a fair amount of
boilerplate, and there are several big scary warning callouts. I've dealt
with many people in #django in a position where they needed a custom user
model, but had already launched the project without one, leaving them with
no good options. Several of these people specifically said that they'd
considered using a custom user model initially, but were scared off by the
docs.
Every single new Django project, even if it doesn't initially need
anything different from the default user model, should start with a two-
line custom user model like this:
{{{
from django.contrib.auth.models import AbstractUser
class User(AbstractUser):
pass
}}}
It's trivial to setup, there is no downside, and there is massive upside:
later in the project, when you realize that you need unique emails, or an
additional field, or some other departure from the default, it's easy to
use migrations to modify an existing custom user model. It's extremely
difficult to migrate from the default user model to a custom user model.
(Ironically, the warnings in the documentation that scare people away from
starting with a custom user model are all about problems with switching to
one mid-stream; problems that would be totally avoided if people did start
off with a custom user model!)
My proposal: we reorganize the "Customizing Authentication" page to
recommend and feature the super-simple custom user model as shown above.
We also link to that page from the tutorial with a recommendation to start
your real project with a custom user model. (I don't know that we should
actually modify the tutorial code, as that's a bit of additional
complexity, but I think people should at least be encouraged to go look at
the auth-customization docs.)
--
Ticket URL: <https://code.djangoproject.com/ticket/24370>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by aaugustin):
* stage: Unreviewed => Accepted
Comment:
+1
Having gone through the pain of doing that change a few times, I can
confirm there is no good solution once you've started without a custom
user model.
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:1>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timgraham):
See also #20629 - "Admonitions in custom User model documentation may be
scaring off users".
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:2>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timgraham):
Would modifying the default project template be going a step too far?
Otherwise, I think most people probably wouldn't come across this until
it's too late unless they are experienced developers.
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:3>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by carljm):
The more I think about changing the default project template, the more I
like the idea. If this is the way you should start a project, why wouldn't
we do it in the default template?
The main downside would just be that it's another concept to understand, a
few more files and lines of code in the default template. And we'd have to
settle the bikeshed of where to put the skeleton custom user model - it
needs to go in an app, and having the startproject template include a pre-
created app in INSTALLED_APPS feels like a significant change.
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:4>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by collinanderson):
* cc: cmawebsite@… (added)
Comment:
Maybe we could make a `manage.py startuserapp` which creates an app with a
custom user that uses an email address as the username by default.
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:5>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.7
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by carljm):
I think adding a second startproject command or template, or adding
something built-in which uses email address is username, is definitely
going too far for this ticket.
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:6>
Django
Reporter: carljm | Owner:
Type: | maestrofjp
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.7
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by maestrofjp):
* owner: nobody => maestrofjp
* status: new => assigned
Comment:
I'd like to help out by making the documentation change to reflect
whatever is decided. I'm assigning myself this ticket -- feel to steal it
back.
I agree @timgraham that modifying the default project template appears to
be way beyond the scope of this ticket. I think a good first step would be
massage the wording around this.
I'm relatively new Django developer (just a couple years) and the wording
around this is very scary. I originally was dissuaded from using a custom
user model, luckily we migrated to one before the application went to
production. However, the transition was still painful as all of our
migrations changed, etc.
If a consensus can be made, I'm happy to update the documentation. Please
advise next steps...
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:7>
Django
Reporter: carljm | Owner:
Type: | maestrofjp
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timgraham):
I think addressing #20629 would be a good start.
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:8>
Django
Reporter: Carl Meyer | Owner: Krzysztof
Type: | Gogolewski
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.7
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Krzysztof Gogolewski):
* owner: maestrofjp => Krzysztof Gogolewski
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:9>
Django
Reporter: Carl Meyer | Owner: Krzysztof
Type: | Gogolewski
Component: Documentation | Version: 1.7
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"d02a03d574b6623ce0d648dd676ae278d46375fb" d02a03d5]:
{{{
#!CommitTicketReference repository=""
revision="d02a03d574b6623ce0d648dd676ae278d46375fb"
Fixed #24370 -- Recommended starting with a custom user model.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:10>
Django
Reporter: Carl Meyer | Owner: Krzysztof
Type: | Gogolewski
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"9f89ca41dbf8a89031f1f29d7ed3ac4e1973018d" 9f89ca41]:
{{{
#!CommitTicketReference repository=""
revision="9f89ca41dbf8a89031f1f29d7ed3ac4e1973018d"
[1.10.x] Fixed #24370 -- Recommended starting with a custom user model.
Backport of d02a03d574b6623ce0d648dd676ae278d46375fb from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/24370#comment:11>