Merge branch 'master' into schema-alteration

24 files changed, 198 insertions, 162 deletions

diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index 143a729f37..b53bbe8211 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -83,9 +83,9 @@ processing at the first positive match.
 
 .. versionadded:: 1.6
 
-If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
-exception, authentication will immediately fail. Django won't check the
-backends that follow.
+    If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
+    exception, authentication will immediately fail. Django won't check the
+    backends that follow.
 
 Writing an authentication backend
 ---------------------------------
@@ -1051,6 +1051,7 @@ code would be required in the app's ``admin.py`` file::
 
         class Meta:
             model = MyUser
+            fields = ['email', 'password', 'date_of_birth', 'is_active', 'is_admin']
 
         def clean_password(self):
             # Regardless of what the user provides, return the initial value.
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index a38ee84841..e666cded75 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -435,10 +435,10 @@ The login_required decorator
 
     .. versionchanged:: 1.5
 
-    The :setting:`settings.LOGIN_URL <LOGIN_URL>` also accepts
-    view function names and :ref:`named URL patterns <naming-url-patterns>`.
-    This allows you to freely remap your login view within your URLconf
-    without having to update the setting.
+        The :setting:`settings.LOGIN_URL <LOGIN_URL>` also accepts
+        view function names and :ref:`named URL patterns <naming-url-patterns>`.
+        This allows you to freely remap your login view within your URLconf
+        without having to update the setting.
 
 .. note::
 
@@ -759,6 +759,7 @@ patterns.
     mail will be sent either.
 
     .. versionchanged:: 1.6
+
         Previously, error messages indicated whether a given email was
         registered.
 
@@ -1041,6 +1042,7 @@ Thus, you can check permissions in template ``{% if %}`` statements:
     {% endif %}
 
 .. versionadded:: 1.5
+
     Permission lookup by "if in".
 
 It is possible to also look permissions up by ``{% if in %}`` statements.
diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt
index 8cd34f8ad9..86c5280159 100644
--- a/docs/topics/class-based-views/generic-editing.txt
+++ b/docs/topics/class-based-views/generic-editing.txt
@@ -114,9 +114,11 @@ here; we don't have to write any logic ourselves::
 
     class AuthorCreate(CreateView):
         model = Author
+        fields = ['name']
 
     class AuthorUpdate(UpdateView):
         model = Author
+        fields = ['name']
 
     class AuthorDelete(DeleteView):
         model = Author
@@ -126,6 +128,17 @@ here; we don't have to write any logic ourselves::
     We have to use :func:`~django.core.urlresolvers.reverse_lazy` here, not
     just ``reverse`` as the urls are not loaded when the file is imported.
 
+.. versionchanged:: 1.6
+
+In Django 1.6, the ``fields`` attribute was added, which works the same way as
+the ``fields`` attribute on the inner ``Meta`` class on
+:class:`~django.forms.ModelForm`.
+
+Omitting the fields attribute will work as previously, but is deprecated and
+this attribute will be required from 1.8 (unless you define the form class in
+another way).
+
+
 Finally, we hook these new views into the URLconf::
 
     # urls.py
@@ -177,33 +190,17 @@ the foreign key relation to the model::
 
         # ...
 
-Create a custom :class:`~django.forms.ModelForm` in order to exclude the
-``created_by`` field and prevent the user from editing it:
-
-.. code-block:: python
-
-    # forms.py
-    from django import forms
-    from myapp.models import Author
-
-    class AuthorForm(forms.ModelForm):
-        class Meta:
-            model = Author
-            exclude = ('created_by',)
-
-In the view, use the custom
-:attr:`~django.views.generic.edit.FormMixin.form_class` and override
-:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the
-user::
+In the view, ensure that you exclude ``created_by`` in the list of fields to
+edit, and override
+:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the user::
 
     # views.py
     from django.views.generic.edit import CreateView
     from myapp.models import Author
-    from myapp.forms import AuthorForm
 
     class AuthorCreate(CreateView):
-        form_class = AuthorForm
         model = Author
+        fields = ['name']
 
         def form_valid(self, form):
             form.instance.created_by = self.request.user
@@ -237,19 +234,24 @@ works for AJAX requests as well as 'normal' form POSTs::
             return HttpResponse(data, **response_kwargs)
 
         def form_invalid(self, form):
+            response = super(AjaxableResponseMixin, self).form_invalid(form)
             if self.request.is_ajax():
                 return self.render_to_json_response(form.errors, status=400)
             else:
-                return super(AjaxableResponseMixin, self).form_invalid(form)
+                return response
 
         def form_valid(self, form):
+            # We make sure to call the parent's form_valid() method because
+            # it might do some processing (in the case of CreateView, it will
+            # call form.save() for example).
+            response = super(AjaxableResponseMixin, self).form_valid(form)
             if self.request.is_ajax():
                 data = {
-                    'pk': form.instance.pk,
+                    'pk': self.object.pk,
                 }
                 return self.render_to_json_response(data)
             else:
-                return super(AjaxableResponseMixin, self).form_valid(form)
+                return response
 
     class AuthorCreate(AjaxableResponseMixin, CreateView):
         model = Author
diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt
index 56bdd16e84..2a0f7e4ce0 100644
--- a/docs/topics/db/managers.txt
+++ b/docs/topics/db/managers.txt
@@ -176,6 +176,7 @@ your choice of default manager in order to avoid a situation where overriding
 work with.
 
 .. versionchanged:: 1.6
+
     The ``get_queryset`` method was previously named ``get_query_set``.
 
 .. _managers-for-related-objects:
diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt
index 182099cc3a..ac329cc4fc 100644
--- a/docs/topics/db/multi-db.txt
+++ b/docs/topics/db/multi-db.txt
@@ -681,6 +681,7 @@ In addition, some objects are automatically created just after
   database).
 
 .. versionchanged:: 1.5
+
     Previously, ``ContentType`` and ``Permission`` instances were created only
     in the default database.
 
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index f19302974d..2553eac27a 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -638,6 +638,7 @@ that were modified more than 3 days after they were published::
     >>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))
 
 .. versionadded:: 1.5
+
     ``.bitand()`` and ``.bitor()``
 
 The ``F()`` objects now support bitwise operations by ``.bitand()`` and
@@ -646,6 +647,7 @@ The ``F()`` objects now support bitwise operations by ``.bitand()`` and
     >>> F('somefield').bitand(16)
 
 .. versionchanged:: 1.5
+
     The previously undocumented operators ``&`` and ``|`` no longer produce
     bitwise operations, use ``.bitand()`` and ``.bitor()`` instead.
 
@@ -1110,15 +1112,6 @@ above example code would look like this::
     >>> b.entries.filter(headline__contains='Lennon')
     >>> b.entries.count()
 
-You cannot access a reverse :class:`~django.db.models.ForeignKey`
-:class:`~django.db.models.Manager` from the class; it must be accessed from an
-instance::
-
-    >>> Blog.entry_set
-    Traceback:
-        ...
-    AttributeError: "Manager must be accessed via instance".
-
 In addition to the :class:`~django.db.models.query.QuerySet` methods defined in
 "Retrieving objects" above, the :class:`~django.db.models.ForeignKey`
 :class:`~django.db.models.Manager` has additional methods used to handle the
diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt
index 34cfa382d3..2ec31a4988 100644
--- a/docs/topics/db/sql.txt
+++ b/docs/topics/db/sql.txt
@@ -211,7 +211,7 @@ For example::
 
     from django.db import connection
 
-    def my_custom_sql():
+    def my_custom_sql(self):
         cursor = connection.cursor()
 
         cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz])
@@ -222,6 +222,7 @@ For example::
         return row
 
 .. versionchanged:: 1.6
+
     In Django 1.5 and earlier, after performing a data changing operation, you
     had to call ``transaction.commit_unless_managed()`` to ensure your changes
     were committed to the database. Since Django now defaults to database-level
diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index d48365dc9e..255584c68b 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -22,6 +22,7 @@ integrity of ORM operations that require multiple queries, especially
 <topics-db-queries-update>` queries.
 
 .. versionchanged:: 1.6
+
     Previous version of Django featured :ref:`a more complicated default
     behavior <transactions-upgrading-from-1.5>`.
 
@@ -73,11 +74,12 @@ To disable this behavior for a specific view, you must set the
 In practice, this feature simply wraps every view function in the :func:`atomic`
 decorator described below.
 
-Note that only the execution of your view in enclosed in the transactions.
-Middleware run outside of the transaction, and so does the rendering of
+Note that only the execution of your view is enclosed in the transactions.
+Middleware runs outside of the transaction, and so does the rendering of
 template responses.
 
 .. versionchanged:: 1.6
+
     Django used to provide this feature via ``TransactionMiddleware``, which is
     now deprecated.
 
@@ -204,6 +206,7 @@ To avoid this, you can :ref:`deactivate the transaction management
 <deactivate-transaction-management>`, but it isn't recommended.
 
 .. versionchanged:: 1.6
+
     Before Django 1.6, autocommit was turned off, and it was emulated by
     forcing a commit after write operations in the ORM.
 
@@ -224,6 +227,7 @@ where you want to run your own transaction-controlling middleware or do
 something really strange.
 
 .. versionchanged:: 1.6
+
     This used to be controlled by the ``TRANSACTIONS_MANAGED`` setting.
 
 Low-level APIs
@@ -312,10 +316,10 @@ rollback that would be performed by ``transaction.rollback()``.
 
 .. versionchanged:: 1.6
 
-When the :func:`atomic` decorator is nested, it creates a savepoint to allow
-partial commit or rollback. You're strongly encouraged to use :func:`atomic`
-rather than the functions described below, but they're still part of the
-public API, and there's no plan to deprecate them.
+    When the :func:`atomic` decorator is nested, it creates a savepoint to allow
+    partial commit or rollback. You're strongly encouraged to use :func:`atomic`
+    rather than the functions described below, but they're still part of the
+    public API, and there's no plan to deprecate them.
 
 Each of these functions takes a ``using`` argument which should be the name of
 a database for which the behavior applies.  If no ``using`` argument is
@@ -354,20 +358,20 @@ The following example demonstrates the use of savepoints::
     @transaction.atomic
     def viewfunc(request):
 
-      a.save()
-      # transaction now contains a.save()
+        a.save()
+        # transaction now contains a.save()
 
-      sid = transaction.savepoint()
+        sid = transaction.savepoint()
 
-      b.save()
-      # transaction now contains a.save() and b.save()
+        b.save()
+        # transaction now contains a.save() and b.save()
 
-      if want_to_keep_b:
-          transaction.savepoint_commit(sid)
-          # open transaction still contains a.save() and b.save()
-      else:
-          transaction.savepoint_rollback(sid)
-          # open transaction now contains only a.save()
+        if want_to_keep_b:
+            transaction.savepoint_commit(sid)
+            # open transaction still contains a.save() and b.save()
+        else:
+            transaction.savepoint_rollback(sid)
+            # open transaction now contains only a.save()
 
 Database-specific notes
 =======================
diff --git a/docs/topics/files.txt b/docs/topics/files.txt
index c05f98ef7e..fb3cdd4af9 100644
--- a/docs/topics/files.txt
+++ b/docs/topics/files.txt
@@ -94,7 +94,7 @@ The following approach may be used to close files automatically::
     True
 
 Closing files is especially important when accessing file fields in a loop
-over a large number of objects:: If files are not manually closed after
+over a large number of objects. If files are not manually closed after
 accessing them, the risk of running out of file descriptors may arise. This
 may lead to the following error::
 
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt
index 269ac5b4b6..9d77cd5274 100644
--- a/docs/topics/forms/formsets.txt
+++ b/docs/topics/forms/formsets.txt
@@ -111,6 +111,7 @@ affect validation.  If ``validate_max=True`` is passed to the
 validation.  See :ref:`validate_max`.
 
 .. versionchanged:: 1.6
+
    The ``validate_max`` parameter was added to
    :func:`~django.forms.formsets.formset_factory`.  Also, the behavior of
    ``FormSet`` was brought in line with that of ``ModelFormSet`` so that it
@@ -310,6 +311,7 @@ should use custom formset validation.
     using forged POST requests.
 
 .. versionchanged:: 1.6
+
    The ``validate_max`` parameter was added to
    :func:`~django.forms.formsets.formset_factory`.
 
diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt
index 98e70e5e77..c0d63bb8cf 100644
--- a/docs/topics/forms/media.txt
+++ b/docs/topics/forms/media.txt
@@ -146,7 +146,7 @@ basic Calendar widget from the example above::
     <script type="text/javascript" src="http://static.example.com/actions.js"></script>
     <script type="text/javascript" src="http://static.example.com/whizbang.js"></script>
 
-The FancyCalendar widget inherits all the media from it's parent widget. If
+The FancyCalendar widget inherits all the media from its parent widget. If
 you don't want media to be inherited in this way, add an ``extend=False``
 declaration to the media declaration::
 
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index eaf2bbbaf2..e58dade736 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -28,6 +28,7 @@ For example::
     >>> class ArticleForm(ModelForm):
     ...     class Meta:
     ...         model = Article
+    ...         fields = ['pub_date', 'headline', 'content', 'reporter']
 
     # Creating a form to add an article.
     >>> form = ArticleForm()
@@ -39,11 +40,13 @@ For example::
 Field types
 -----------
 
-The generated ``Form`` class will have a form field for every model field. Each
-model field has a corresponding default form field. For example, a
-``CharField`` on a model is represented as a ``CharField`` on a form. A
-model ``ManyToManyField`` is represented as a ``MultipleChoiceField``. Here is
-the full list of conversions:
+The generated ``Form`` class will have a form field for every model field
+specified, in the order specified in the ``fields`` attribute.
+
+Each model field has a corresponding default form field. For example, a
+``CharField`` on a model is represented as a ``CharField`` on a form. A model
+``ManyToManyField`` is represented as a ``MultipleChoiceField``. Here is the
+full list of conversions:
 
 ===============================  ========================================
 Model field                      Form field
@@ -168,10 +171,13 @@ Consider this set of models::
     class AuthorForm(ModelForm):
         class Meta:
             model = Author
+            fields = ['name', 'title', 'birth_date']
 
     class BookForm(ModelForm):
         class Meta:
             model = Book
+            fields = ['name', 'authors']
+
 
 With these models, the ``ModelForm`` subclasses above would be roughly
 equivalent to this (the only difference being the ``save()`` method, which
@@ -288,47 +294,66 @@ method is used to determine whether a form requires multipart file upload (and
 hence whether ``request.FILES`` must be passed to the form), etc. See
 :ref:`binding-uploaded-files` for more information.
 
-Using a subset of fields on the form
-------------------------------------
+.. _modelforms-selecting-fields:
 
-In some cases, you may not want all the model fields to appear on the generated
-form. There are three ways of telling ``ModelForm`` to use only a subset of the
-model fields:
+Selecting the fields to use
+---------------------------
 
-1. Set ``editable=False`` on the model field. As a result, *any* form
-   created from the model via ``ModelForm`` will not include that
-   field.
+It is strongly recommended that you explicitly set all fields that should be
+edited in the form using the ``fields`` attribute. Failure to do so can easily
+lead to security problems when a form unexpectedly allows a user to set certain
+fields, especially when new fields are added to a model. Depending on how the
+form is rendered, the problem may not even be visible on the web page.
 
-2. Use the ``fields`` attribute of the ``ModelForm``'s inner ``Meta``
-   class.  This attribute, if given, should be a list of field names
-   to include in the form. The order in which the fields names are specified
-   in that list is respected when the form renders them.
+The alternative approach would be to include all fields automatically, or
+blacklist only some. This fundamental approach is known to be much less secure
+and has led to serious exploits on major websites (e.g. `GitHub
+<https://github.com/blog/1068-public-key-security-vulnerability-and-mitigation>`_).
 
-3. Use the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta``
-   class.  This attribute, if given, should be a list of field names
-   to exclude from the form.
+There are, however, two shortcuts available for cases where you can guarantee
+these security concerns do not apply to you:
 
-For example, if you want a form for the ``Author`` model (defined
-above) that includes only the ``name`` and ``birth_date`` fields, you would
-specify ``fields`` or ``exclude`` like this::
+1. Set the ``fields`` attribute to the special value ``'__all__'`` to indicate
+   that all fields in the model should be used. For example::
 
-    class PartialAuthorForm(ModelForm):
-        class Meta:
-            model = Author
-            fields = ('name', 'birth_date')
+       class AuthorForm(ModelForm):
+           class Meta:
+               model = Author
+               fields = '__all__'
 
-    class PartialAuthorForm(ModelForm):
-        class Meta:
-            model = Author
-            exclude = ('title',)
+2. Set the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta`` class to
+   a list of fields to be excluded from the form.
+
+   For example::
+
+       class PartialAuthorForm(ModelForm):
+           class Meta:
+               model = Author
+               exclude = ['title']
+
+   Since the ``Author`` model has the 3 fields ``name``, ``title`` and
+   ``birth_date``, this will result in the fields ``name`` and ``birth_date``
+   being present on the form.
+
+If either of these are used, the order the fields appear in the form will be the
+order the fields are defined in the model, with ``ManyToManyField`` instances
+appearing last.
+
+In addition, Django applies the following rule: if you set ``editable=False`` on
+the model field, *any* form created from the model via ``ModelForm`` will not
+include that field.
+
+.. versionchanged:: 1.6
+
+    Before version 1.6, the ``'__all__'`` shortcut did not exist, but omitting
+    the ``fields`` attribute had the same effect. Omitting both ``fields`` and
+    ``exclude`` is now deprecated, but will continue to work as before until
+    version 1.8
 
-Since the Author model has only 3 fields, 'name', 'title', and
-'birth_date', the forms above will contain exactly the same fields.
 
 .. note::
 
-    If you specify ``fields`` or ``exclude`` when creating a form with
-    ``ModelForm``, then the fields that are not in the resulting form
+    Any fields not included in a form by the above logic
     will not be set by the form's ``save()`` method. Also, if you
     manually add the excluded fields back to the form, they will not
     be initialized from the model instance.
@@ -401,15 +426,19 @@ field, you could do the following::
 
         class Meta:
             model = Article
+            fields = ['pub_date', 'headline', 'content', 'reporter']
+
 
 If you want to override a field's default label, then specify the ``label``
 parameter when declaring the form field::
 
-   >>> class ArticleForm(ModelForm):
-   ...     pub_date = DateField(label='Publication date')
-   ...
-   ...     class Meta:
-   ...         model = Article
+    class ArticleForm(ModelForm):
+        pub_date = DateField(label='Publication date')
+
+        class Meta:
+            model = Article
+            fields = ['pub_date', 'headline', 'content', 'reporter']
+
 
 .. note::
 
@@ -436,6 +465,7 @@ parameter when declaring the form field::
 
             class Meta:
                 model = Article
+                fields = ['headline', 'content']
 
     You must ensure that the type of the form field can be used to set the
     contents of the corresponding model field. When they are not compatible,
@@ -444,30 +474,6 @@ parameter when declaring the form field::
     See the :doc:`form field documentation </ref/forms/fields>` for more information
     on fields and their arguments.
 
-Changing the order of fields
-----------------------------
-
-By default, a ``ModelForm`` will render fields in the same order that they are
-defined on the model, with ``ManyToManyField`` instances appearing last. If
-you want to change the order in which fields are rendered, you can use the
-``fields`` attribute on the ``Meta`` class.
-
-The ``fields`` attribute defines the subset of model fields that will be
-rendered, and the order in which they will be rendered. For example given this
-model::
-
-    class Book(models.Model):
-        author = models.ForeignKey(Author)
-        title = models.CharField(max_length=100)
-
-the ``author`` field would be rendered first. If we wanted the title field
-to be rendered first, we could specify the following ``ModelForm``::
-
-    >>> class BookForm(ModelForm):
-    ...     class Meta:
-    ...         model = Book
-    ...         fields = ('title', 'author')
-
 .. _overriding-modelform-clean-method:
 
 Overriding the clean() method
@@ -550,21 +556,19 @@ definition. This may be more convenient if you do not have many customizations
 to make::
 
     >>> from django.forms.models import modelform_factory
-    >>> BookForm = modelform_factory(Book)
+    >>> BookForm = modelform_factory(Book, fields=("author", "title"))
 
 This can also be used to make simple modifications to existing forms, for
-example by specifying which fields should be displayed::
-
-    >>> Form = modelform_factory(Book, form=BookForm, fields=("author",))
-
-... or which fields should be excluded::
-
-    >>> Form = modelform_factory(Book, form=BookForm, exclude=("title",))
-
-You can also specify the widgets to be used for a given field::
+example by specifying the widgets to be used for a given field::
 
     >>> from django.forms import Textarea
-    >>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()})
+    >>> Form = modelform_factory(Book, form=BookForm,
+                                 widgets={"title": Textarea()})
+
+The fields to include can be specified using the ``fields`` and ``exclude``
+keyword arguments, or the corresponding attributes on the ``ModelForm`` inner
+``Meta`` class. Please see the ``ModelForm`` :ref:`modelforms-selecting-fields`
+documentation.
 
 .. _model-formsets:
 
@@ -688,11 +692,10 @@ database. If a given instance's data didn't change in the bound data, the
 instance won't be saved to the database and won't be included in the return
 value (``instances``, in the above example).
 
-When fields are missing from the form (for example because they have
-been excluded), these fields will not be set by the ``save()``
-method. You can find more information about this restriction, which
-also holds for regular ``ModelForms``, in `Using a subset of fields on
-the form`_.
+When fields are missing from the form (for example because they have been
+excluded), these fields will not be set by the ``save()`` method. You can find
+more information about this restriction, which also holds for regular
+``ModelForms``, in `Selecting the fields to use`_.
 
 Pass ``commit=False`` to return the unsaved model instances::
 
diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt
index 18243c77ce..503d4322e0 100644
--- a/docs/topics/http/middleware.txt
+++ b/docs/topics/http/middleware.txt
@@ -204,6 +204,7 @@ Dealing with streaming responses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. versionchanged:: 1.5
+
     ``response`` may also be an :class:`~django.http.StreamingHttpResponse`
     object.
 
diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt
index f5c688e254..acad61eb2a 100644
--- a/docs/topics/http/sessions.txt
+++ b/docs/topics/http/sessions.txt
@@ -71,6 +71,7 @@ default cache. To use another cache, set :setting:`SESSION_CACHE_ALIAS` to the
 name of that cache.
 
 .. versionchanged:: 1.5
+
     The :setting:`SESSION_CACHE_ALIAS` setting was added.
 
 Once your cache is configured, you've got two choices for how to store data in
@@ -451,6 +452,7 @@ Similarly, the ``expires`` part of a session cookie is updated each time the
 session cookie is sent.
 
 .. versionchanged:: 1.5
+
   The session is not saved if the response's status code is 500.
 
 .. _browser-length-vs-persistent-sessions:
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 961f0b9d96..52a2935977 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -51,6 +51,7 @@ Optional arguments
     the :setting:`DEFAULT_CONTENT_TYPE` setting.
 
     .. versionchanged:: 1.5
+
         This parameter used to be called ``mimetype``.
 
 ``status``
@@ -129,6 +130,7 @@ Optional arguments
     the :setting:`DEFAULT_CONTENT_TYPE` setting.
 
     .. versionchanged:: 1.5
+
         This parameter used to be called ``mimetype``.
 
 
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 811425d229..2ce9d8d2bc 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1030,11 +1030,11 @@ prepend the current active language code to all url patterns defined within
     from django.conf.urls import patterns, include, url
     from django.conf.urls.i18n import i18n_patterns
 
-    urlpatterns = patterns(''
+    urlpatterns = patterns('',
         url(r'^sitemap\.xml$', 'sitemap.view', name='sitemap_xml'),
     )
 
-    news_patterns = patterns(''
+    news_patterns = patterns('',
         url(r'^$', 'news.views.index', name='index'),
         url(r'^category/(?P<slug>[\w-]+)/$', 'news.views.category', name='category'),
         url(r'^(?P<slug>[\w-]+)/$', 'news.views.details', name='detail'),
@@ -1529,6 +1529,7 @@ selection based on data from the request. It customizes content for each user.
 ``'django.middleware.locale.LocaleMiddleware'``.
 
 .. versionchanged:: 1.6
+
     In previous versions, ``LocaleMiddleware``  wasn't enabled by default.
 
 Because middleware order matters, you should follow these guidelines:
diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt
index cb22a57e84..a31dc01cc5 100644
--- a/docs/topics/logging.txt
+++ b/docs/topics/logging.txt
@@ -169,7 +169,7 @@ issued on the ``project.interesting`` and
 ``project.interesting.stuff`` loggers.
 
 This propagation can be controlled on a per-logger basis. If
-you don't want a particular logger to propagate to it's parents, you
+you don't want a particular logger to propagate to its parents, you
 can turn off this behavior.
 
 Making logging calls
diff --git a/docs/topics/pagination.txt b/docs/topics/pagination.txt
index 17747c22ff..9da71563c3 100644
--- a/docs/topics/pagination.txt
+++ b/docs/topics/pagination.txt
@@ -252,7 +252,7 @@ Methods
 
     .. versionchanged:: 1.5
 
-    Raises :exc:`InvalidPage` if next page doesn't exist.
+        Raises :exc:`InvalidPage` if next page doesn't exist.
 
 .. method:: Page.previous_page_number()
 
@@ -260,7 +260,7 @@ Methods
 
     .. versionchanged:: 1.5
 
-    Raises :exc:`InvalidPage` if previous page doesn't exist.
+        Raises :exc:`InvalidPage` if previous page doesn't exist.
 
 .. method:: Page.start_index()
 
diff --git a/docs/topics/python3.txt b/docs/topics/python3.txt
index 33f5fcd4c0..22e609c75c 100644
--- a/docs/topics/python3.txt
+++ b/docs/topics/python3.txt
@@ -317,6 +317,9 @@ Division
         def __idiv__(self, other):  # Python 2 compatibility
             return type(self).__itruediv__(self, other)
 
+Special methods are looked up on the class and not on the instance to reflect
+the behavior of the Python interpreter.
+
 .. module: django.utils.six
 
 Writing compatible code with six
diff --git a/docs/topics/security.txt b/docs/topics/security.txt
index 566202eefa..22135a72ea 100644
--- a/docs/topics/security.txt
+++ b/docs/topics/security.txt
@@ -168,7 +168,7 @@ certain cases. While these values are sanitized to prevent Cross Site Scripting
 attacks, a fake ``Host`` value can be used for Cross-Site Request Forgery,
 cache poisoning attacks, and poisoning links in emails.
 
-Because even seemingly-secure webserver configurations are susceptible to fake
+Because even seemingly-secure web server configurations are susceptible to fake
 ``Host`` headers, Django validates ``Host`` headers against the
 :setting:`ALLOWED_HOSTS` setting in the
 :meth:`django.http.HttpRequest.get_host()` method.
@@ -181,15 +181,15 @@ For more details see the full :setting:`ALLOWED_HOSTS` documentation.
 
 .. warning::
 
-   Previous versions of this document recommended configuring your webserver to
+   Previous versions of this document recommended configuring your web server to
    ensure it validates incoming HTTP ``Host`` headers. While this is still
-   recommended, in many common webservers a configuration that seems to
+   recommended, in many common web servers a configuration that seems to
    validate the ``Host`` header may not in fact do so. For instance, even if
    Apache is configured such that your Django site is served from a non-default
    virtual host with the ``ServerName`` set, it is still possible for an HTTP
    request to match this virtual host and supply a fake ``Host`` header. Thus,
    Django now requires that you set :setting:`ALLOWED_HOSTS` explicitly rather
-   than relying on webserver configuration.
+   than relying on web server configuration.
 
 Additionally, as of 1.3.1, Django requires you to explicitly enable support for
 the ``X-Forwarded-Host`` header (via the :setting:`USE_X_FORWARDED_HOST`
diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt
index ce39f6cd28..cb34117997 100644
--- a/docs/topics/serialization.txt
+++ b/docs/topics/serialization.txt
@@ -124,8 +124,8 @@ Calling ``DeserializedObject.save()`` saves the object to the database.
 
 .. versionchanged:: 1.6
 
-In previous versions of Django, the ``pk`` attribute had to be present
-on the serialized data or a ``DeserializationError`` would be raised.
+    In previous versions of Django, the ``pk`` attribute had to be present
+    on the serialized data or a ``DeserializationError`` would be raised.
 
 This ensures that deserializing is a non-destructive operation even if the
 data in your serialized representation doesn't match what's currently in the
@@ -144,11 +144,11 @@ The Django object itself can be inspected as ``deserialized_object.object``.
 
 .. versionadded:: 1.5
 
-If fields in the serialized data do not exist on a model,
-a ``DeserializationError`` will be raised unless the ``ignorenonexistent``
-argument is passed in as True::
+    If fields in the serialized data do not exist on a model,
+    a ``DeserializationError`` will be raised unless the ``ignorenonexistent``
+    argument is passed in as True::
 
-    serializers.deserialize("xml", data, ignorenonexistent=True)
+        serializers.deserialize("xml", data, ignorenonexistent=True)
 
 .. _serialization-formats:
 
diff --git a/docs/topics/signals.txt b/docs/topics/signals.txt
index d611da4a37..a97fb2f14f 100644
--- a/docs/topics/signals.txt
+++ b/docs/topics/signals.txt
@@ -134,7 +134,7 @@ to.
 
 .. versionchanged:: 1.5
 
-The ability to pass a list of signals was added.
+    The ability to pass a list of signals was added.
 
 .. admonition:: Where should this code live?
 
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index 26dc8ee1ae..5f2fa65bed 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -163,10 +163,12 @@ environment first. Django provides a convenience method to do this::
     >>> from django.test.utils import setup_test_environment
     >>> setup_test_environment()
 
-This convenience method sets up the test database, and puts other
-Django features into modes that allow for repeatable testing.
+:func:`~django.test.utils.setup_test_environment` puts several Django features
+into modes that allow for repeatable testing, but does not create the test
+databases; :func:`django.test.simple.DjangoTestSuiteRunner.setup_databases`
+takes care of that.
 
-The call to :meth:`~django.test.utils.setup_test_environment` is made
+The call to :func:`~django.test.utils.setup_test_environment` is made
 automatically as part of the setup of ``./manage.py test``. You only
 need to manually invoke this method if you're not using running your
 tests via Django's test runner.
@@ -282,7 +284,9 @@ Methods
 
 .. method:: DjangoTestSuiteRunner.setup_test_environment(**kwargs)
 
-    Sets up the test environment ready for testing.
+    Sets up the test environment by calling
+    :func:`~django.test.utils.setup_test_environment` and setting
+    :setting:`DEBUG` to ``False``.
 
 .. method:: DjangoTestSuiteRunner.build_suite(test_labels, extra_tests=None, **kwargs)
 
@@ -340,6 +344,9 @@ Methods
 Testing utilities
 -----------------
 
+django.test.utils
+~~~~~~~~~~~~~~~~~
+
 .. module:: django.test.utils
    :synopsis: Helpers to write custom test runners.
 
@@ -358,10 +365,13 @@ utility methods in the ``django.test.utils`` module.
     magic hooks into the template system and restoring normal email
     services.
 
+django.db.connection.creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. currentmodule:: django.db.connection.creation
 
-The creation module of the database backend (``connection.creation``)
-also provides some utilities that can be useful during testing.
+The creation module of the database backend also provides some utilities that
+can be useful during testing.
 
 .. function:: create_test_db([verbosity=1, autoclobber=False])
 
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt
index 259c39618b..9228a07b31 100644
--- a/docs/topics/testing/overview.txt
+++ b/docs/topics/testing/overview.txt
@@ -25,7 +25,7 @@ module defines tests in class-based approach.
     adding some extremely useful features. To ensure that every Django
     project can benefit from these new features, Django ships with a
     copy of unittest2_, a copy of the Python 2.7 unittest library,
-    backported for Python 2.5 compatibility.
+    backported for Python 2.6 compatibility.
 
     To access this library, Django provides the
     ``django.utils.unittest`` module alias. If you are using Python
@@ -235,6 +235,7 @@ the Django test runner reorders tests in the following way:
   restoring it to its original state are run.
 
 .. versionchanged:: 1.5
+
     Before Django 1.5, the only guarantee was that
     :class:`~django.test.TestCase` tests were always ran first, before any other
     tests.
@@ -612,6 +613,7 @@ Use the ``django.test.client.Client`` class to make requests.
         a ``Content-Type`` header is set to ``content_type``.
 
         .. versionchanged:: 1.5
+
             :meth:`Client.options` used to process ``data`` like
             :meth:`Client.get`.
 
@@ -627,6 +629,7 @@ Use the ``django.test.client.Client`` class to make requests.
         a ``Content-Type`` header is set to ``content_type``.
 
         .. versionchanged:: 1.5
+
             :meth:`Client.put` used to process ``data`` like
             :meth:`Client.post`.
 
@@ -650,6 +653,7 @@ Use the ``django.test.client.Client`` class to make requests.
         a ``Content-Type`` header is set to ``content_type``.
 
         .. versionchanged:: 1.5
+
             :meth:`Client.delete` used to process ``data`` like
             :meth:`Client.get`.
 
@@ -940,6 +944,7 @@ to test the effects of commit and rollback:
     the test has been properly updated.
 
 .. versionchanged:: 1.5
+
     The order in which tests are run has changed. See `Order in which tests are
     executed`_.
 
@@ -990,6 +995,7 @@ additions, including:
   errors.
 
 .. versionchanged:: 1.5
+
     The order in which tests are run has changed. See `Order in which tests are
     executed`_.
 
@@ -1581,6 +1587,7 @@ your test suite.
     ``False``, which turns the comparison into a Python set comparison.
 
     .. versionchanged:: 1.6
+
         The method now checks for undefined order and raises ``ValueError``
         if undefined order is spotted. The ordering is seen as undefined if
         the given ``qs`` isn't ordered and the comparison is against more