migration guide for StatelessSession and second-level cache

Author: gavinking

migration-guide.adoc

@@ -381,6 +381,19 @@ must be explicitly set to true.
 
 The signature of the `Configurable#configure` method changed from accepting just a `ServiceRegistry` instance to the new `GeneratorCreationContext` interface, which exposes a lot more useful information when configuring the generator itself. The old signature has been deprecated for removal, so you should migrate any custom `Configurable` generator implementation to the new one.
 
+[[stateless-session-cache]]
+== `StatelessSession` and second-level cache
+
+Previously, stateless sessions never interacted with the second-level cache.
+This reflected their original intended role in bulk processing.
+With the advent of Jakarta Data and Hibernate Data Repositories, the responsibilities of `StatelessSession` have now expanded, and this behavior is no longer appropriate.
+
+Thus, a stateless session now makes use of the second-level cache by default.
+To completely bypass the second-level cache, recovering the previous behavior, call `setCacheMode(CacheMode.IGNORE)`.
+
+It's often important to explicitly disable puts to the second-level cache in code which performs bulk processing.
+Set the cache mode to `GET` or configure `jakarta.persistence.cache.storeMode` to `BYPASS`.
+
 [[stateless-session-jdbc-batching]]
 == JDBC batching with `StatelessSession`