2 files changed, 35 insertions, 1 deletions
diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index 6cbfd88ac6..6ca2581397 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -21,9 +21,13 @@ Fields
 
     .. attribute:: username
 
-        Required. 30 characters or fewer. Usernames may contain alphanumeric,
+        Required. 254 characters or fewer. Usernames may contain alphanumeric,
         ``_``, ``@``, ``+``, ``.`` and ``-`` characters.
 
+        .. versionchanged:: 1.10
+
+            The ``max_length`` increased from 30 to 254 characters.
+
     .. attribute:: first_name
 
         Optional. 30 characters or fewer.
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index 602e34a6f9..b291dcfd41 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -258,6 +258,36 @@ to its proxied concrete class. This inconsistency was fixed by returning the
 full set of fields pointing to a concrete class or one of its proxies in both
 cases.
 
+:attr:`AbstractUser.username <django.contrib.auth.models.User.username>` ``max_length`` increased to 254
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A migration for :attr:`django.contrib.auth.models.User.username` is included.
+If you have a custom user model inheriting from ``AbstractUser``, you'll need
+to generate and apply a database migration for your user model.
+
+If you want to preserve the 30 character limit for usernames, use a custom form
+when creating a user or changing usernames::
+
+    from django.contrib.auth.forms import UserCreationForm
+
+    class MyUserCreationForm(UserCreationForm):
+        username = forms.CharField(
+            max_length=30,
+            help_text='Required. 30 characters or fewer. Letters, digits and @/./+/-/_ only.',
+        )
+
+If you wish to keep this restriction in the admin, set ``UserAdmin.add_form``
+to use this form::
+
+    from django.contrib.auth.admin import UserAdmin
+    from django.contrib.auth.models import User
+
+    class MyUserAdmin(UserAdmin):
+        add_form = MyUserCreationForm
+
+    admin.site.unregister(User)
+    admin.site.register(User, MyUserAdmin)
+
 Miscellaneous
 ~~~~~~~~~~~~~