Fixed #28786 -- Doc'd middleware ordering considerations due to CommonMiddleware setting Content-Length.

2 files changed, 10 insertions, 0 deletions

diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index cfa6a77665..35407493f7 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -471,6 +471,10 @@ Here are some hints about the ordering of various Django middleware classes:
 
 #. :class:`~django.middleware.common.CommonMiddleware`
 
+   Before any middleware that may change the response (it sets the
+   ``Content-Length`` header). A middleware that appears before
+   ``CommonMiddleware`` and changes the response must reset ``Content-Length``.
+
    Close to the top: it redirects when :setting:`APPEND_SLASH` or
    :setting:`PREPEND_WWW` are set to ``True``.
 
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index ff4c1ebfef..9e84b869d3 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -730,6 +730,12 @@ Miscellaneous
   ``Content-Length`` header as this is now done by
   :class:`~django.middleware.common.CommonMiddleware`.
 
+  If you have a middleware that modifies a response's content and appears
+  before ``CommonMiddleware`` in the ``MIDDLEWARE`` or ``MIDDLEWARE_CLASSES``
+  settings, you must reorder your middleware so that responses aren't modified
+  after ``Content-Length`` is set, or have the response modifying middleware
+  reset the ``Content-Length`` header.
+
 * :meth:`~django.apps.AppConfig.get_model` and
   :meth:`~django.apps.AppConfig.get_models` now raise
   :exc:`~django.core.exceptions.AppRegistryNotReady` if they're called before