Merge pull request #8214 from open-sausages/pulls/3/docs-upgrading-se…

…ssion-usage

DOCS Upgrading 3.x docs on session stage param

docs/en/04_Changelogs/3.7.0.md

@@ -198,6 +198,39 @@ class Page_Controller extends ContentController
    other layers such as Apache's mod_gzip.
 <!--- Changes below this line will be automatically regenerated -->
 
+## Disable session-based stage setting
+
+When viewing a versioned record (usually pages) in "draft" mode,
+SilverStripe records this mode in the session for further requests.
+This has the advantage of transparently working on XHR and API requests,
+as well as authenticated users navigating through other views.
+
+These subsequent requests no longer carried an explicit `stage` query parameter,
+which meant the same URL might show draft or live content depending on your session state.
+While most HTTP caching layers deal gracefully with this variation by disabling
+any caching when a session cookie is present, there is a small chance
+that draft content is exposed to unauthenticated users for the lifetime of the cache.
+
+Due to this potential risk for information leakage,
+we have decided to only rely on the `stage` query parameter starting with SilverStripe 4.2.
+In SilverStripe 3.x, you can opt-in to this behaviour as well:
+
+```yml
+SilverStripe\Versioned\Versioned:
+  use_session: false
+```
+
+If you are consistently using the built-in `SiteTree->Link()`
+and `Controller->Link()` methods to get URLs, this change likely won't affect you. 
+
+If you are manually concatenating URLs to SilverStripe controllers
+rather than through their `Link()` methods (in custom PHP or JavaScript),
+or have implemented your own `Link()` methods on controllers exposing
+versioned objects, you'll need to check your business logic.
+
+Check our [versioning docs](/developer_guides/model/versioning#controllers)
+for more details.
+
 ## Change Log
 
 ### Security