Alphabetized a few sections in the 1.9 release notes + made a few tweaks.

1 files changed, 89 insertions, 85 deletions

diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 6bacdb1ae2..704f2b4e4f 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -6,9 +6,9 @@ Welcome to Django 1.9!
 
 These release notes cover the `new features`_, as well as some `backwards
 incompatible changes`_ you'll want to be aware of when upgrading from Django
-1.8 or older versions. We've :ref:`dropped some features
-<deprecation-removed-in-1.9>` that have reached the end of their deprecation
-cycle, and we've `begun the deprecation process for some features`_.
+1.8 or older versions. We've :ref:`dropped some features<removed-features-1.9>`
+that have reached the end of their deprecation cycle, and we've `begun the
+deprecation process for some features`_.
 
 .. _`new features`: `What's new in Django 1.9`_
 .. _`backwards incompatible changes`: `Backwards incompatible changes in 1.9`_
@@ -18,9 +18,11 @@ cycle, and we've `begun the deprecation process for some features`_.
 Python compatibility
 ====================
 
-Like Django 1.8, Django 1.9 requires Python 2.7 or above, though we
-**highly recommend** the latest minor release. We've dropped support for
-Python 3.2 and 3.3, and added support for Python 3.5.
+Django 1.9 requires Python 2.7, 3.4, or 3.5. We **highly recommend** and only
+officially support the latest release of each series.
+
+Since Django 1.8, we've dropped support for Python 3.2 and 3.3, and added
+support for Python 3.5.
 
 What's new in Django 1.9
 ========================
@@ -197,8 +199,8 @@ Minor features
 
 * ``AbstractBaseUser`` and ``BaseUserManager`` were moved to a new
   ``django.contrib.auth.base_user`` module so that they can be imported without
-  including ``django.contrib.auth`` in :setting:`INSTALLED_APPS` (this raised
-  a deprecation warning in older versions and is no longer supported in
+  including ``django.contrib.auth`` in :setting:`INSTALLED_APPS` (doing so
+  raised a deprecation warning in older versions and is no longer supported in
   Django 1.9).
 
 * The permission argument of
@@ -320,6 +322,26 @@ Cache
   headers (added ``no-cache, no-store, must-revalidate`` to ``Cache-Control``)
   to better prevent caching.
 
+CSRF
+^^^^
+
+* The request header's name used for CSRF authentication can be customized
+  with :setting:`CSRF_HEADER_NAME`.
+
+* The CSRF referer header is now validated against the
+  :setting:`CSRF_COOKIE_DOMAIN` setting if set. See :ref:`how-csrf-works` for
+  details.
+
+* The new :setting:`CSRF_TRUSTED_ORIGINS` setting provides a way to allow
+  cross-origin unsafe requests (e.g. ``POST``) over HTTPS.
+
+Database backends
+^^^^^^^^^^^^^^^^^
+
+* The PostgreSQL backend (``django.db.backends.postgresql_psycopg2``) is also
+  available as ``django.db.backends.postgresql``. The old name will continue to
+  be available for backwards compatibility.
+
 Email
 ^^^^^
 
@@ -539,18 +561,49 @@ Models
 * Added a new model field check that makes sure
   :attr:`~django.db.models.Field.default` is a valid value.
 
-CSRF
-^^^^
+Requests and Responses
+^^^^^^^^^^^^^^^^^^^^^^
 
-* The request header's name used for CSRF authentication can be customized
-  with :setting:`CSRF_HEADER_NAME`.
+* Unless :attr:`HttpResponse.reason_phrase
+  <django.http.HttpResponse.reason_phrase>` is explicitly set, it now is
+  determined by the current value of :attr:`HttpResponse.status_code
+  <django.http.HttpResponse.status_code>`. Modifying the value of
+  ``status_code`` outside of the constructor will also modify the value of
+  ``reason_phrase``.
 
-* The CSRF referer header is now validated against the
-  :setting:`CSRF_COOKIE_DOMAIN` setting if set. See :ref:`how-csrf-works` for
-  details.
+* The debug view now shows details of chained exceptions on Python 3.
 
-* The new :setting:`CSRF_TRUSTED_ORIGINS` setting provides a way to allow
-  cross-origin unsafe requests (e.g. ``POST``) over HTTPS.
+* The default 40x error views now accept a second positional parameter, the
+  exception that triggered the view.
+
+* View error handlers now support
+  :class:`~django.template.response.TemplateResponse`, commonly used with
+  class-based views.
+
+* Exceptions raised by the ``render()`` method are now passed to the
+  ``process_exception()`` method of each middleware.
+
+* Request middleware can now set :attr:`HttpRequest.urlconf
+  <django.http.HttpRequest.urlconf>` to ``None`` to revert any changes made
+  by previous middleware and return to using the :setting:`ROOT_URLCONF`.
+
+* The :setting:`DISALLOWED_USER_AGENTS` check in
+  :class:`~django.middleware.common.CommonMiddleware` now raises a
+  :class:`~django.core.exceptions.PermissionDenied` exception as opposed to
+  returning an :class:`~django.http.HttpResponseForbidden` so that
+  :data:`~django.conf.urls.handler403` is invoked.
+
+* Added :meth:`HttpRequest.get_port() <django.http.HttpRequest.get_port>` to
+  fetch the originating port of the request.
+
+* Added the ``json_dumps_params`` parameter to
+  :class:`~django.http.JsonResponse` to allow passing keyword arguments to the
+  ``json.dumps()`` call used to generate the response.
+
+* The :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` now
+  ignores 404s when the referer is equal to the requested URL. To circumvent
+  the empty referer check already implemented, some Web bots set the referer to
+  the requested URL.
 
 Signals
 ^^^^^^^
@@ -594,50 +647,6 @@ Templates
 * The ``include`` tag now caches parsed templates objects during template
   rendering, speeding up reuse in places such as for loops.
 
-Requests and Responses
-^^^^^^^^^^^^^^^^^^^^^^
-
-* Unless :attr:`HttpResponse.reason_phrase
-  <django.http.HttpResponse.reason_phrase>` is explicitly set, it now is
-  determined by the current value of :attr:`HttpResponse.status_code
-  <django.http.HttpResponse.status_code>`. Modifying the value of
-  ``status_code`` outside of the constructor will also modify the value of
-  ``reason_phrase``.
-
-* The debug view now shows details of chained exceptions on Python 3.
-
-* The default 40x error views now accept a second positional parameter, the
-  exception that triggered the view.
-
-* View error handlers now support
-  :class:`~django.template.response.TemplateResponse`, commonly used with
-  class-based views.
-
-* Exceptions raised by the ``render()`` method are now passed to the
-  ``process_exception()`` method of each middleware.
-
-* Request middleware can now set :attr:`HttpRequest.urlconf
-  <django.http.HttpRequest.urlconf>` to ``None`` to revert any changes made
-  by previous middleware and return to using the :setting:`ROOT_URLCONF`.
-
-* The :setting:`DISALLOWED_USER_AGENTS` check in
-  :class:`~django.middleware.common.CommonMiddleware` now raises a
-  :class:`~django.core.exceptions.PermissionDenied` exception as opposed to
-  returning an :class:`~django.http.HttpResponseForbidden` so that
-  :data:`~django.conf.urls.handler403` is invoked.
-
-* Added :meth:`HttpRequest.get_port() <django.http.HttpRequest.get_port>` to
-  fetch the originating port of the request.
-
-* Added the ``json_dumps_params`` parameter to
-  :class:`~django.http.JsonResponse` to allow passing keyword arguments to the
-  ``json.dumps()`` call used to generate the response.
-
-* The :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` now
-  ignores 404s when the referer is equal to the requested URL. To circumvent
-  the empty referer check already implemented, some Web bots set the referer to
-  the requested URL.
-
 Tests
 ^^^^^
 
@@ -671,23 +680,16 @@ Validators
 * Added :func:`~django.core.validators.validate_unicode_slug` to validate slugs
   that may contain Unicode characters.
 
-Database backends
-^^^^^^^^^^^^^^^^^
-
-* The PostgreSQL backend (``django.db.backends.postgresql_psycopg2``) is also
-  available as ``django.db.backends.postgresql``. The old name will continue to
-  be available for backwards compatibility.
-
 Backwards incompatible changes in 1.9
 =====================================
 
 .. warning::
 
     In addition to the changes outlined in this section, be sure to review the
-    :doc:`deprecation timeline </internals/deprecation>` for any features that
-    have been removed. If you haven't updated your code within the
-    deprecation timeline for a given feature, its removal may appear as a
-    backwards incompatible change.
+    :ref:`removed-features-1.9` for the features that have reached the end of
+    their deprecation cycle and therefore been removed. If you haven't updated
+    your code within the deprecation timeline for a given feature, its removal
+    may appear as a backwards incompatible change.
 
 Database backend API
 ~~~~~~~~~~~~~~~~~~~~
@@ -753,17 +755,18 @@ setuptools is not installed.
 Related set direct assignment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:ref:`Direct assignment <direct-assignment>`) used to perform a ``clear()``
-followed by a call to ``add()``. This caused needlessly large data changes
-and prevented using the :data:`~django.db.models.signals.m2m_changed` signal
-to track individual changes in many-to-many relations.
+:ref:`Direct assignment <direct-assignment>` of related objects in the ORM used
+to perform a ``clear()`` followed by a call to ``add()``. This caused
+needlessly large data changes and prevented using the
+:data:`~django.db.models.signals.m2m_changed` signal to track individual
+changes in many-to-many relations.
 
 Direct assignment now relies on the the new
-:meth:`django.db.models.fields.related.RelatedManager.set()` method on
-related managers which by default only processes changes between the
-existing related set and the one that's newly assigned. The previous behavior
-can be restored by replacing direct assignment by a call to ``set()`` with
-the keyword argument ``clear=True``.
+:meth:`~django.db.models.fields.related.RelatedManager.set` method on related
+managers which by default only processes changes between the existing related
+set and the one that's newly assigned. The previous behavior can be restored by
+replacing direct assignment by a call to ``set()`` with the keyword argument
+``clear=True``.
 
 ``ModelForm``, and therefore ``ModelAdmin``, internally rely on direct
 assignment for many-to-many relations and as a consequence now use the new
@@ -883,8 +886,8 @@ queries, you should turn them into naive datetimes in UTC::
     from django.utils import timezone
     param = timezone.make_naive(param, timezone.utc)
 
-If you fail to do so, Django 1.9 and 2.0 will perform the conversion like
-earlier versions but emit a deprecation warning. Django 2.0 won't perform any
+If you fail to do so, the conversion will be performed as in earlier versions
+(with a deprecation warning) up until Django 1.11. Django 2.0 won't perform any
 conversion, which may result in data corruption.
 
 If you're reading :class:`~datetime.datetime` values from the results, they
@@ -1021,7 +1024,8 @@ Miscellaneous
   ``vendor/jquery`` subdirectory.
 
 * The text displayed for null columns in the admin changelist ``list_display``
-  cells has changed from ``(None)`` (or its translated equivalent) to ``-``.
+  cells has changed from ``(None)`` (or its translated equivalent) to ``-`` (a
+  dash).
 
 * ``django.http.responses.REASON_PHRASES`` and
   ``django.core.handlers.wsgi.STATUS_CODE_TEXT`` have been removed. Use
@@ -1297,7 +1301,7 @@ Miscellaneous
   deprecated. Use the new ``enclosures`` argument which accepts a list of
   ``Enclosure`` objects instead of a single one.
 
-.. removed-features-1.9:
+.. _removed-features-1.9:
 
 Features removed in 1.9
 =======================