Add documentation for #17573

Fixes some parts of #23148.

[ci skip]

2 files changed, 11 insertions, 0 deletions

diff --git a/actionpack/lib/action_dispatch/http/cache.rb b/actionpack/lib/action_dispatch/http/cache.rb
index 0f7898a3f8..4bd727c14e 100644
--- a/actionpack/lib/action_dispatch/http/cache.rb
+++ b/actionpack/lib/action_dispatch/http/cache.rb
@@ -80,6 +80,14 @@ module ActionDispatch
           set_header DATE, utc_time.httpdate
         end
 
+        # This method allows you to set the ETag for cached content, which
+        # will be returned to the end user.
+        #
+        # By default, Action Dispatch sets all ETags to be weak.
+        # This ensures that if the content changes only semantically,
+        # the whole page doesn't have to be regenerated from scratch
+        # by the web server. With strong ETags, pages are compared
+        # byte by byte, and are regenerated only if they are not exactly equal.
         def etag=(etag)
           key = ActiveSupport::Cache.expand_cache_key(etag)
           super %(W/"#{Digest::MD5.hexdigest(key)}")
diff --git a/guides/source/5_0_release_notes.md b/guides/source/5_0_release_notes.md
index 2650384df3..f45c8005da 100644
--- a/guides/source/5_0_release_notes.md
+++ b/guides/source/5_0_release_notes.md
@@ -253,6 +253,9 @@ Please refer to the [Changelog][action-pack] for detailed changes.
     `ActionDispatch::IntegrationTest` instead.
     ([commit](https://github.com/rails/rails/commit/4414c5d1795e815b102571425974a8b1d46d932d))
 
+*   Rails will only generate "weak", instead of strong ETags.
+    ([Pull Request](https://github.com/rails/rails/pull/17573))
+
 Action View
 -------------