From 8b4fb6ef0f14a703aef36dbb8d73fbf24954a8d8 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 26 Mar 2013 19:01:11 +0100
Subject: [PATCH] Clarified 3.1 upgrading docs

---
 docs/en/changelogs/3.1.0.md | 55 ++++++++++++++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 7 deletions(-)

diff --git a/docs/en/changelogs/3.1.0.md b/docs/en/changelogs/3.1.0.md
index e760b0448..2d08c92d0 100644
--- a/docs/en/changelogs/3.1.0.md
+++ b/docs/en/changelogs/3.1.0.md
@@ -33,7 +33,7 @@
 
 ## Upgrading
 
-### Static configuration properties are now immutable, you must use Config API.
+### Static properties are immutable and private, you must use Config API.
 
 A common SilverStripe pattern is to use a static variable on a class to define a configuration parameter.
 The configuration system added in SilverStripe 3.0 builds on this by using this static variable as a way
@@ -75,6 +75,8 @@ Here's an example on how to rewrite a common `_config.php` configuration:
 		SSViewer::set_theme('basic');
 	}
 
+	Object::add_extension('Member', 'MyMemberExtension');
+
 The ugpraded `_config.php`:
 
 	:::php
@@ -106,6 +108,9 @@ The upgraded `config.yml`:
 	---
 	SSViewer:
 	  theme: 'simple'
+	Member:
+	  extensions:
+	    MyMemberExtension
 	---
 	Only:
 	  environment: 'live'
@@ -121,18 +126,54 @@ Some examples of changed notations (not exhaustive, there's over a hundred in to
  * `Director::setBaseURL`: Use `Director.alternate_base_url` instead
  * `SSViewer::setOption('rewriteHashlinks', ...)`: Use `SSViewer.rewrite_hashlinks` instead
 
-**Important**: Please remember to upgrade the installer project as well, particularly
+<div class="warning" markdown='1'>
+Please remember to upgrade the installer project as well, particularly
 your `.htaccess` or `web.config` files. Web access to these sensitive YAML configuration files 
 needs to be explicitly denied through these configuration files (see the [3.0.5 security release](/changelogs/3.0.4))
 for details.
-
-This change will also affect any visibility modifiers on `SiteTree` subclasses
-in your own codebase, since those are further extended by SilverStripe core,
-e.g. `ErrorPage extends Page`.  Please change all "core statics" like `$db`, `$has_one`,
-`$has_many`, `$many_many`, `$defaults`, etc to `private` visibility.
+</div>
 
 For more information about how to use the config system, see the ["Configuration" topic](/topic/configuration).
 
+### Statics in custom Page classes need to be "private"
+
+Related to the configuration change described above, many statics in core are now
+marked with `private` visibility. While PHP allows making variables more visible
+(e.g. from "private" to "public"), it complains if you try to restrict visibility in subclasses.
+The core framework extends from the `Page` class in your own codebase (`mysite/`),
+which means you need to change those statics to `private` yourself.
+The same rules apply to controllers subclassd from `Page_Controller`.
+
+Before:
+
+	:::php
+	<?php
+	class Page extends SiteTree {
+		static $db = array('MyVar' => 'Text');
+	}
+	class Page_Controller extends ContentController {
+		static $allowed_actions = array('myaction');
+	}
+
+After:
+
+	:::php
+	<?php
+	class Page extends SiteTree {
+		private static $db = array('MyVar' => 'Text');
+	}
+	class Page_Controller extends ContentController {
+		private static $allowed_actions = array('myaction');
+	}
+
+Most statics defined in `SiteTree` and `DataObject` are affected, for example:
+`$db`, `$has_one`, `$has_many`, `$many_many`, `$defaults`, `$allowed_children`.
+The same goes for statics defined in `ContentController`, e.g. `$allowed_actions`.
+
+Classes which are not further extended by the core (e.g. all custom `DataObject` subclasses)
+are not affected by this change, although we recommend to mark those inherited statics
+as `private` as well, to make it clear that they should be accessed through the Config API.
+
 ### default_cast is now Text
 
 In order to reduce the chance of accidentally allowing XSS attacks, the value of default_cast