Merge pull request #42076 from Shopify/document-as-cache-upgrade

Document the new Active Support cache format

activesupport/CHANGELOG.md

@@ -1,3 +1,13 @@
+*   Added a faster and more compact `ActiveSupport::Cache` serialization format.
+
+    It can be enabled with `config.active_support.cache_format_version = 7.0` or
+    `config.load_defaults(7.0)`. Regardless of the configuration Active Support
+    7.0 can read cache entries serialized by Active Support 6.1 which allows to
+    upgrade without invalidating the cache. However Rails 6.1 can't read the
+    new format, so all readers must be upgraded before the new format is enabled.
+
+    *Jean Boussier*
+
 *   Add `Enumerable#sole`, per `ActiveRecord::FinderMethods#sole`.  Returns the
     sole item of the enumerable, raising if no items are found, or if more than
     one is.

guides/source/caching_with_rails.md

@@ -364,6 +364,8 @@ There are some common options that can be used by all cache implementations. The
 
 * `:race_condition_ttl` - This option is used in conjunction with the `:expires_in` option. It will prevent race conditions when cache entries expire by preventing multiple processes from simultaneously regenerating the same entry (also known as the dog pile effect). This option sets the number of seconds that an expired entry can be reused while a new value is being regenerated. It's a good practice to set this value if you use the `:expires_in` option.
 
+* `:coder` - This option allows to replace the default cache entry serialization mechanism by a custom one. The `coder` must respond to `dump` and `load`, and passing a custom coder disable automatic compression.
+
 #### Connection Pool Options
 
 By default the `MemCacheStore` and `RedisCacheStore` use a single connection

guides/source/upgrading_ruby_on_rails.md

@@ -122,6 +122,35 @@ This has consequences for things like Etags that will change and cache keys as w
 Changing these keys can have impact on cache hit rates, so be careful and watch out
 for this when upgrading to the new hash.
 
+### New ActiveSupport::Cache serialization format
+
+A faster and more compact serialization format was introduced.
+
+To enable it you must set `config.active_support.cache_format_version = 7.0`:
+
+```ruby
+# config/application.rb
+
+config.load_defaults(6.1)
+config.active_support.cache_format_version = 7.0
+```
+
+Or simply:
+
+```ruby
+# config/application.rb
+
+config.load_defaults(7.0)
+```
+
+However Rails 6.1 applications are not able to read this new serialization format,
+so to ensure a seemless upgrade you must first deploy your Rails 7.0 upgrade with
+`config.active_support.cache_format_version = 6.1`, and then only once all Rails
+processes have been updated you can set `config.active_support.cache_format_version = 7.0`.
+
+Rails 7.0 is able to read both formats so the cache won't be invalidated during the
+upgrade.
+
 Upgrading from Rails 6.0 to Rails 6.1
 -------------------------------------