Fixed #26447 -- Deprecated settings.USE_ETAGS in favor of ConditionalGetMiddleware.

8 files changed, 46 insertions, 15 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index a7ef1b8be5..2d247d8f65 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -43,6 +43,9 @@ details on these changes.
 
 * The ``django.db.models.permalink()`` decorator will be removed.
 
+* The ``USE_ETAGS`` setting will be removed. ``CommonMiddleware`` and
+  ``django.utils.cache.patch_response_headers()`` will no longer set ETags.
+
 .. _deprecation-removed-in-2.0:
 
 2.0
diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 5d8939e3ef..432f5437ff 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -72,6 +72,12 @@ Adds a few conveniences for perfectionists:
 
     Older versions didn't set the ``Content-Length`` header.
 
+.. deprecated:: 1.11
+
+    The :setting:`USE_ETAGS` setting is deprecated in favor of using
+    :class:`~django.middleware.http.ConditionalGetMiddleware` for ETag
+    processing.
+
 .. attribute:: CommonMiddleware.response_redirect_class
 
 Defaults to :class:`~django.http.HttpResponsePermanentRedirect`. Subclass
@@ -166,13 +172,18 @@ Conditional GET middleware
 
 .. class:: ConditionalGetMiddleware
 
-Handles conditional GET operations. If the response has a ``ETag`` or
+Handles conditional GET operations. If the response doesn't have an ``ETag``
+header, the middleware adds one if needed. If the response has a ``ETag`` or
 ``Last-Modified`` header, and the request has ``If-None-Match`` or
 ``If-Modified-Since``, the response is replaced by an
 :class:`~django.http.HttpResponseNotModified`.
 
 Also sets the ``Date`` and ``Content-Length`` response-headers.
 
+.. versionchanged:: 1.11
+
+    In older versions, the middleware didn't set the ``ETag`` header.
+
 Locale middleware
 -----------------
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 05faa734b2..28240034e5 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2532,6 +2532,11 @@ bandwidth but slows down performance. This is used by the
 :class:`~django.middleware.common.CommonMiddleware` and in the :doc:`cache
 framework </topics/cache>`.
 
+.. deprecated:: 1.11
+
+    This setting is deprecated in favor of using ``ConditionalGetMiddleware``,
+    which sets an ETag regardless of this setting.
+
 .. setting:: USE_I18N
 
 ``USE_I18N``
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index a9072f9442..45ffd80fc4 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -65,6 +65,11 @@ need to distinguish caches by the ``Accept-language`` header.
 
         In older versions, the ``Last-Modified`` header was also set.
 
+    .. deprecated:: 1.11
+
+        Since the ``USE_ETAGS`` setting is deprecated, this function won't set
+        the ``ETag`` header when the deprecation ends in Django 2.1.
+
 .. function:: add_never_cache_headers(response)
 
     Adds a ``Cache-Control: max-age=0, no-cache, no-store, must-revalidate``
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index ff77ebeabb..3be654eff5 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -327,6 +327,9 @@ Requests and Responses
 * Added the :setting:`SECURE_HSTS_PRELOAD` setting to allow appending the
   ``preload`` directive to the ``Strict-Transport-Security`` header.
 
+* :class:`~django.middleware.http.ConditionalGetMiddleware` now adds the
+  ``ETag`` header to responses.
+
 Serialization
 ~~~~~~~~~~~~~
 
@@ -633,3 +636,9 @@ Miscellaneous
 * :func:`~django.contrib.auth.authenticate` now passes a ``request`` argument
   to the ``authenticate()`` method of authentication backends. Support for
   methods that don't accept ``request`` will be removed in Django 2.1.
+
+* The ``USE_ETAGS`` setting is deprecated in favor of
+  :class:`~django.middleware.http.ConditionalGetMiddleware` which now adds the
+  ``ETag`` header to responses regardless of the setting. ``CommonMiddleware``
+  and ``django.utils.cache.patch_response_headers()`` will no longer set ETags
+  when the deprecation ends.
diff --git a/docs/topics/conditional-view-processing.txt b/docs/topics/conditional-view-processing.txt
index 7398b3fd05..7f1fde0fb9 100644
--- a/docs/topics/conditional-view-processing.txt
+++ b/docs/topics/conditional-view-processing.txt
@@ -11,7 +11,7 @@ used for all HTTP methods (``POST``, ``PUT``, ``DELETE``, etc.).
 For each page (response) that Django sends back from a view, it might provide
 two HTTP headers: the ``ETag`` header and the ``Last-Modified`` header. These
 headers are optional on HTTP responses. They can be set by your view function,
-or you can rely on the :class:`~django.middleware.common.CommonMiddleware`
+or you can rely on the :class:`~django.middleware.http.ConditionalGetMiddleware`
 middleware to set the ``ETag`` header.
 
 When the client next requests the same resource, it might send along a header
@@ -189,17 +189,14 @@ every time.
 Comparison with middleware conditional processing
 =================================================
 
-You may notice that Django already provides simple and straightforward
-conditional ``GET`` handling via the
-:class:`django.middleware.http.ConditionalGetMiddleware` and
-:class:`~django.middleware.common.CommonMiddleware`. While certainly being
-easy to use and suitable for many situations, those pieces of middleware
-functionality have limitations for advanced usage:
+Django provides simple and straightforward conditional ``GET`` handling via
+:class:`django.middleware.http.ConditionalGetMiddleware`. While being easy to
+use and suitable for many situations, the middleware has limitations for
+advanced usage:
 
-* They are applied globally to all views in your project
-* They don't save you from generating the response itself, which may be
-  expensive
-* They are only appropriate for HTTP ``GET`` requests.
+* It's applied globally to all views in your project.
+* It doesn't save you from generating the response, which may be expensive.
+* It's only appropriate for HTTP ``GET`` requests.
 
 You should choose the most appropriate tool for your particular problem here.
 If you have a way to compute ETags and modification times quickly and if some
diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 4ef0ae45a3..db891f75d7 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -1372,8 +1372,8 @@ URL::
     ]
 
 Client-side caching will save bandwidth and make your site load faster. If
-you're using ETags (:setting:`USE_ETAGS = True <USE_ETAGS>`), you're already
-covered. Otherwise, you can apply :ref:`conditional decorators
+you're using ETags (:class:`~django.middleware.http.ConditionalGetMiddleware`),
+you're already covered. Otherwise, you can apply :ref:`conditional decorators
 <conditional-decorators>`. In the following example, the cache is invalidated
 whenever you restart your application server::
 
diff --git a/docs/topics/performance.txt b/docs/topics/performance.txt
index c8c9d231af..8f2516a4eb 100644
--- a/docs/topics/performance.txt
+++ b/docs/topics/performance.txt
@@ -262,7 +262,8 @@ that can help optimize your site's performance. They include:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Adds support for modern browsers to conditionally GET responses based on the
-``ETag`` and ``Last-Modified`` headers.
+``ETag`` and ``Last-Modified`` headers. It also calculates and sets an ETag if
+needed.
 
 :class:`~django.middleware.gzip.GZipMiddleware`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~