django/django — pull request #669 by tomchristie (2013-01-24 17:07:10+00:00)
Title: Note `authenticate` usage with custom user model.

If using a custom user model, with eg `USERNAME_FIELD='email'`,
then it is non-obvious if the correct usage is `authenticate(username=..., password=...)` or `authenticate(email=..., password=...)`

Bit of an easy stumbling point, and it won't be obvious to the developer why login is failing, so we should really note the usage here.

This was the best phrasing I could come up with, but happy to take other suggestions.