Don't recommend using a custom user model when starting a new project

[Carlton Gibson]

Following ​the forum discussion here, adjust the customizing user model docs to remove the recommendation of requiring a custom User model and tone down the warning about mid-project migrations a notch.

​PR implementing that.

[Natalia Bidart]

Amazing, thank you Carlton.

[Natalia Bidart]

I have approved the PR but added a non trivial suggestion. Setting as patch needs improvement until I hear back from Carlton, so this is moved out from the review queue. I will update accordingly based on responses tomorrow.

[GitHub <noreply@…>]

In c0128e3a:

Fixed #35767 -- Adjusted customizing User model docs.

[Natalia <124304+nessita@…>]

In d96b661:

[5.1.x] Fixed #35767 -- Adjusted customizing User model docs.

Backport of c0128e3a81cfb07238324b185958a88631e94963 from main.

[Tim Graham]

Since all changes "adjust" things, try to use a better description. ;-)

[Carlton Gibson]

Thanks Tim! 😊

[Tim Graham]

For the record, I think it's premature to remove the recommendation and tone down the warning, given all the chaos in #25313. Unless the plan is to deprecate AUTH_MODEL_USER...

For instance, comment:29:ticket:25313:

At the start of our first real Django project we anticipated needing authentication eventually, so followed instructions from ​​https://docs.djangoproject.com/en/4.0/topics/auth/customizing/#customizing-authentication-in-django. (we expected to use an email address instead of username for the identification token). We basically stubbed it until we knew what we needed. For our 2nd project we thought we would never need authentication so did nothing relating to users. We are now likely to nuke our databases and rebuild to avoid the migration complications described in this ticket.

Given the impact of customizing authentication mid-project, why doesn't the default setup simply create an appropriate stub? Is the problem choosing an appropriate stub? Maybe that's easier than solving migration?

I just closed #27909 (Use AUTH_USER_MODEL in startproject template) as wontfix since it contradicts the change in this ticket.

One week since the initial forum post seems kind of fast to conclude a long-standing discussion about this topic.

[Carlton Gibson]

Hey Tim.

Thanks for closing the issue. Yes… I can see that line. I argued at length why I don't agree, but I'd suggest that the 8 years that #27909 was unresolved is exactly indication that the problems I've diagnosed are real. Numerous attempts to progress the tutorial and start project template have come to nothing because a sensible work around for the custom user model problem couldn't be found. There comes a point where we have to say enough is enough: this discussion has been stagnant for essentially an age. I put forward a very minimal change to move us from the impasse. I was somewhat surprised how positive the response was, but it's only on the basis of that response that I opened the ticket.

Unless the plan is to deprecate AUTH_MODEL_USER...

We so far away from actually removing it that I don't know how to sensibly think about that. My suggestion is that we fix the complaints about auth.User — login by email being the main one — and then custom users models should just fade away. I can't see it being something to remove though.

To be honest, I find the quoted comment misleading and alarmist. Migrating isn't that hard, even if you're convinced it's necessary (which of course I'm going to say it's not, right). The suggestion from the community is to document those steps. I think that's a good idea.

I don't want to repeat everything I've written elsewhere, but I'm really happy to chat with you about this. I value your opinion. I've argued that auth is the leaky battery. I don't think the issues with auth.User are insurmountable. Imagine if we actually addressed them. What a much better story we could tell. I don't know if you agree with any of what I said, but I'd love to have your input pushing forward here.

[Tim Graham]

I was surprised we would remove the warning without documenting the migration steps. Part of the reason the warning was added is because the migration process is difficult.

It's extremely difficult to migrate from the default user model to a custom user model.
-Carl in #24370

I guess you would favor a wontfix on such documentation (#25313) and instead promote the user profile approach.

[Carlton Gibson]

No, I think there was keenness to move the steps there to a proper _How To_. I have no problem with that at all.

The (minimal) goal here was simply to remove the impression (to new users, stumbling upon it) that (with hyperbole, but that's how it get interpreted) there's some need for tearing down your project and starting again if you didn't use a custom user model.

As per the diff on the PR, a small tweak was all that was entailed.

I've written at length elsewhere my wider views, which are pretty conservative. I'm not out to shake up the world.