id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
32791	Documentation unclear on custom user models	Matthew Somerville	Nishant Sagar	"At https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project it says ""If you’re starting a new project, it’s highly recommended to set up a custom user model, even if the default User model is sufficient for you."" and shows a subclass of AbstractUser as a starting example.

Yet a few sections down at https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#specifying-a-custom-user-model it says ""When you start your project with a custom user model, stop to consider if this is the right choice for your project."" and then recommends inheriting from AbstractBaseUser. - But the docs told me it's highly recommended as the right choice :)

Then further down again at https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#extending-django-s-default-user it says ""If you’re entirely happy with Django’s User model, but you want to add some additional profile information, you could subclass django.contrib.auth.models.AbstractUser and add your custom profile fields, although we’d recommend a separate model as described in the “Model design considerations” note of Specifying a custom user model."" - but in the first section you specifically gave an example of subclassing AbstractUser, so how can it now not be recommended in the same document.

Recommending the AbstractUser subclass comes from #24370 and the second part comes from toning down the message, in #20629. After reading this for a new project, I am quite confused. I made a start at trying to tidy it up, but I wasn't sure what would actually come first and what it should say where, so decided to open this ticket instead."	Uncategorized	closed	Documentation	3.2	Normal	needsinfo			Unreviewed	0	0	0	0	0	0