DOCSP-44184: cache version method

source/index.txt

@@ -1,9 +1,9 @@
 .. _mongoid-odm-landing:
 .. _mongoid-odm:
 
-================================
+====================================
 {+odm+}: The ODM for MongoDB in Ruby
-================================
+====================================
 
 .. toctree::
    :titlesonly:

source/whats-new.txt

@@ -30,6 +30,26 @@ fixes:
   as raw hashes. To learn more, see the :ref:`mongoid-raw-results`
   section of the Modify Query Results guide.
 
+- Improves caching functionality by modifying the behavior of
+  ``cache_key`` to *not* embed a timestamp when ``cache_version``
+  returns a non-nil value. Instead, the timestamp is used as the version
+  for the entry to reduce key churn.
+
+  This change also adds the ``cache_version`` method to the
+  ``Mongoid::Document`` module. If the cache key format introduced in
+  this version poses an issue in your application, you can revert to
+  the original format by defining the ``cache_version`` method as
+  ``nil``:
+
+  .. code-block:: ruby
+     :emphasize-lines: 3
+
+     module Mongoid
+       module Document
+         def cache_version = nil
+       end
+     end
+
 .. _mongoid-version-9.0:
 
 What's New in 9.0