Document scoping issue with Time.use_zone

The Time.use_zone method will only affect ActiveSupport::TimeWithZone
instances created inside of the block passed to Time.use_zone. This
could be confusing when fetching a model and then reading the attribute
before the block and it not changing afterwards because Active Record
caches the conversion from the database value.

Since changing the behavior of Active Record to recreate the value on
every attribute read is an expensive operation the best we can do is
to document the issue.

Fixes #23195.

[ci skip]

1 files changed, 17 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb
index 877dc84ec8..7a60f94996 100644
--- a/activesupport/lib/active_support/core_ext/time/zones.rb
+++ b/activesupport/lib/active_support/core_ext/time/zones.rb
@@ -40,7 +40,23 @@ class Time
       Thread.current[:time_zone] = find_zone!(time_zone)
     end
 
-    # Allows override of <tt>Time.zone</tt> locally inside supplied block; resets <tt>Time.zone</tt> to existing value when done.
+    # Allows override of <tt>Time.zone</tt> locally inside supplied block;
+    # resets <tt>Time.zone</tt> to existing value when done.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     around_action :set_time_zone
+    #
+    #     private
+    #
+    #     def set_time_zone
+    #       Time.use_zone(current_user.timezone) { yield }
+    #     end
+    #   end
+    #
+    #  NOTE: This won't affect any <tt>ActiveSupport::TimeWithZone</tt>
+    #  objects that have already been created, e.g. any model timestamp
+    #  attributes that have been read before the block will remain in
+    #  the application's default timezone.
     def use_zone(time_zone)
       new_zone = find_zone!(time_zone)
       begin