Fixed #26601 -- Improved middleware per DEP 0005.

Thanks Tim Graham for polishing the patch, updating the tests, and
writing documentation. Thanks Carl Meyer for shepherding the DEP.

docs/ref/contrib/admin/index.txt

@@ -41,8 +41,8 @@ For reference, here are the requirements:
    defined in your :setting:`TEMPLATES` as well as
    :class:`django.contrib.auth.middleware.AuthenticationMiddleware` and
    :class:`django.contrib.messages.middleware.MessageMiddleware` to
-   :setting:`MIDDLEWARE_CLASSES`. (These are all active by default, so
-   you only need to do this if you've manually tweaked the settings.)
+   :setting:`MIDDLEWARE`. These are all active by default, so you only need to
+   do this if you've manually tweaked the settings.
 
 4. Determine which of your application's models should be editable in the
    admin interface.

docs/ref/contrib/flatpages.txt

@@ -53,7 +53,7 @@ Then either:
 or:
 
 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
-   to your :setting:`MIDDLEWARE_CLASSES` setting.
+   to your :setting:`MIDDLEWARE` setting.
 
 4. Run the command :djadmin:`manage.py migrate <migrate>`.
 
@@ -144,8 +144,7 @@ can do all of the work.
    methods. Only requests which are successfully routed to a view via
    normal URL resolution apply view middleware.
 
-Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
-can put
+Note that the order of :setting:`MIDDLEWARE` matters. Generally, you can put
 :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at the
 end of the list. This means it will run first when processing the response, and
 ensures that any other response-processing middlewares see the real flatpage

docs/ref/contrib/messages.txt

@@ -27,14 +27,14 @@ already contains all the settings required to enable message functionality:
 
 * ``'django.contrib.messages'`` is in :setting:`INSTALLED_APPS`.
 
-* :setting:`MIDDLEWARE_CLASSES` contains
+* :setting:`MIDDLEWARE` contains
   ``'django.contrib.sessions.middleware.SessionMiddleware'`` and
   ``'django.contrib.messages.middleware.MessageMiddleware'``.
 
   The default :ref:`storage backend <message-storage-backends>` relies on
   :doc:`sessions </topics/http/sessions>`. That's why ``SessionMiddleware``
   must be enabled and appear before ``MessageMiddleware`` in
-  :setting:`MIDDLEWARE_CLASSES`.
+  :setting:`MIDDLEWARE`.
 
 * The ``'context_processors'`` option of the ``DjangoTemplates`` backend
   defined in your :setting:`TEMPLATES` setting contains
@@ -42,8 +42,8 @@ already contains all the settings required to enable message functionality:
 
 If you don't want to use messages, you can remove
 ``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`, the
-``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, and the
-``messages`` context processor from :setting:`TEMPLATES`.
+``MessageMiddleware`` line from :setting:`MIDDLEWARE`, and the ``messages``
+context processor from :setting:`TEMPLATES`.
 
 Configuring the message engine
 ==============================

docs/ref/contrib/redirects.txt

@@ -18,7 +18,7 @@ To install the redirects app, follow these steps:
    :ref:`is installed <enabling-the-sites-framework>`.
 2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
 3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
-   to your :setting:`MIDDLEWARE_CLASSES` setting.
+   to your :setting:`MIDDLEWARE` setting.
 4. Run the command :djadmin:`manage.py migrate <migrate>`.
 
 How it works
@@ -49,9 +49,9 @@ given ``old_path`` with a site ID that corresponds to the
 The middleware only gets activated for 404s -- not for 500s or responses of any
 other status code.
 
-Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you
-can put :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`
-at the end of the list, because it's a last resort.
+Note that the order of :setting:`MIDDLEWARE` matters. Generally, you can put
+:class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware` at the
+end of the list, because it's a last resort.
 
 For more on middleware, read the :doc:`middleware docs
 </topics/http/middleware>`.

docs/ref/contrib/sites.txt

@@ -405,8 +405,8 @@ If you often use this pattern::
 
 there is simple way to avoid repetitions. Add
 :class:`django.contrib.sites.middleware.CurrentSiteMiddleware` to
-:setting:`MIDDLEWARE_CLASSES`. The middleware sets the ``site`` attribute on
-every request object, so you can use ``request.site`` to get the current site.
+:setting:`MIDDLEWARE`. The middleware sets the ``site`` attribute on every
+request object, so you can use ``request.site`` to get the current site.
 
 How Django uses the sites framework
 ===================================