From 8c56506a058889fb294e303509a8521d3c84b5e0 Mon Sep 17 00:00:00 2001
From: Aaron Carlino <unclecheese@leftandmain.com>
Date: Wed, 30 May 2018 16:00:41 +1200
Subject: [PATCH] Add upgrade docs

---
 docs/en/04_Changelogs/4.2.0.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/en/04_Changelogs/4.2.0.md b/docs/en/04_Changelogs/4.2.0.md
index bd6ebc7db..9fc2c7055 100644
--- a/docs/en/04_Changelogs/4.2.0.md
+++ b/docs/en/04_Changelogs/4.2.0.md
@@ -171,3 +171,33 @@ $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config);
 // method 2: removing GridField_ActionMenu from an existing GridField
 $gridField->getConfig()->removeComponentsByType(GridField_ActionMenu);
 ```
+### Versioned cache segmentation
+
+The cache API now maintains separate cache pools for each versioned stage. This prevents users from caching draft data and then exposing it on the live stage.
+
+```php
+// Before:
+$cache = Injector::inst()->get(CacheInterface::class . '.myapp');
+Versioned::set_stage(Versioned::DRAFT);
+$cache->set('my_key', 'Some draft content. Not for public viewing yet.');
+Versioned::set_stage(Versioned::LIVE);
+$cache->get('my_key'); // 'Some draft content. Not for public viewing yet'
+
+// After:
+$cache = Injector::inst()->get(CacheInterface::class . '.myapp');
+Versioned::set_stage(Versioned::DRAFT);
+$cache->set('my_key', 'Some draft content. Not for public viewing yet.');
+Versioned::set_stage(Versioned::LIVE);
+$cache->get('my_key'); // null
+```
+Data that is not content sensitive can be cached across stages by simply opting out of the segmented cache with the `disable-container` argument.
+
+```yaml
+SilverStripe\Core\Injector\Injector:
+  Psr\SimpleCache\CacheInterface.myapp:
+    factory: SilverStripe\Core\Cache\CacheFactory     
+    constructor:
+      namespace: "MyInsensitiveData"
+      args:
+        disable-container: true 
+```