From 70144ad54906c5c5a6854f436b8b3601a6d1cc99 Mon Sep 17 00:00:00 2001
From: Will Rossiter <will.rossiter@gmail.com>
Date: Tue, 26 Mar 2013 22:05:37 +1300
Subject: [PATCH 1/7] FIX: Groups should be able to have titles longer than 50
 characters (Fixes: open/5611)

---
 security/Group.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/security/Group.php b/security/Group.php
index be68cfec7..2d4f0f1d4 100755
--- a/security/Group.php
+++ b/security/Group.php
@@ -8,12 +8,12 @@
 class Group extends DataObject {
 	
 	private static $db = array(
-		"Title" => "Varchar",
+		"Title" => "Varchar(255)",
 		"Description" => "Text",
-		"Code" => "Varchar",
+		"Code" => "Varchar(255)",
 		"Locked" => "Boolean",
 		"Sort" => "Int",
-		"HtmlEditorConfig" => "Varchar"
+		"HtmlEditorConfig" => "Text"
 	);
 	
 	private static $has_one = array(

From 880702fc7400dfab88eada5194635f99792a1378 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 26 Mar 2013 10:13:00 +0100
Subject: [PATCH 2/7] Fixed static config access in Currency and i18n (fixes
 #8341)

---
 i18n/i18n.php                 | 2 +-
 model/fieldtypes/Currency.php | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/i18n/i18n.php b/i18n/i18n.php
index e2b150d57..a16b1993d 100644
--- a/i18n/i18n.php
+++ b/i18n/i18n.php
@@ -1765,7 +1765,7 @@ class i18n extends Object implements TemplateGlobalProvider {
 	 * @return Name of the locale
 	 */
 	public static function get_locale_name($code) {
-		$langs = self::get_locale_list();
+		$langs = self::config()->all_locales;
 		return isset($langs[$code]) ? $langs[$code] : false;
 	}
 	
diff --git a/model/fieldtypes/Currency.php b/model/fieldtypes/Currency.php
index 8517a33a3..a3b831740 100644
--- a/model/fieldtypes/Currency.php
+++ b/model/fieldtypes/Currency.php
@@ -66,7 +66,7 @@ class Currency extends Decimal {
 	
 	public static function setCurrencySymbol($value) {
 		Deprecation::notice('3.2', 'Use the "Currency.currency_symbol" config setting instead');
-		$this->config()->currency_symbol = $value;
+		Currency::config()->currency_symbol = $value;
 	}
 }
 

From 04c3b5ee949529402d168efe183a7de1402c324f Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 26 Mar 2013 10:15:17 +0100
Subject: [PATCH 3/7] Fixed static config in BBCodeParser (fixes #8340)

---
 parsers/BBCodeParser.php | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/parsers/BBCodeParser.php b/parsers/BBCodeParser.php
index de260f1ca..e77299b60 100644
--- a/parsers/BBCodeParser.php
+++ b/parsers/BBCodeParser.php
@@ -43,7 +43,7 @@ class BBCodeParser extends TextParser {
 		if(!BBCodeParser::$smilies_location) {
 			return FRAMEWORK_DIR . '/images/smilies';
 		}
-		return $this->config()->smilies_location;
+		return static::config()->smilies_location;
 	}
 
 	/**
@@ -51,7 +51,7 @@ class BBCodeParser extends TextParser {
 	 */
 	public static function set_icon_folder($path) {
 		Deprecation::notice('3.2', 'Use the "BBCodeParser.smilies_location" config setting instead');
-		$this->config()->smilies_location = $path;
+		static::config()->smilies_location = $path;
 	} 
 	
 	/**
@@ -59,7 +59,7 @@ class BBCodeParser extends TextParser {
 	 */
 	public static function autolinkUrls() {
 		Deprecation::notice('3.2', 'Use the "BBCodeParser.autolink_urls" config setting instead');
-		return $this->config()->autolink_urls;
+		return static::config()->autolink_urls;
 	}
 	
 	/**
@@ -67,7 +67,7 @@ class BBCodeParser extends TextParser {
 	 */
 	public static function disable_autolink_urls($autolink = false) {
 		Deprecation::notice('3.2', 'Use the "BBCodeParser.autolink_urls" config setting instead');
-		$this->config()->autolink_urls = $autolink;
+		static::config()->autolink_urls = $autolink;
 	}
 	
 	/**
@@ -75,7 +75,7 @@ class BBCodeParser extends TextParser {
 	 */
 	public static function smiliesAllowed() {
 		Deprecation::notice('3.2', 'Use the "BBCodeParser.allow_smilies" config setting instead');
-		return $this->config()->allow_smilies;
+		return static::config()->allow_smilies;
 	}
 	
 	/**
@@ -83,7 +83,7 @@ class BBCodeParser extends TextParser {
 	 */
 	public static function enable_smilies() {
 		Deprecation::notice('3.2', 'Use the "BBCodeParser.allow_smilies" config setting instead');
-		$this->config()->allow_similies = true;
+		static::config()->allow_similies = true;
 	}
 	
 	

From a415db91d44ccde50a5ed0b1c35ec4d450ae5b2d Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 26 Mar 2013 12:47:52 +0100
Subject: [PATCH 4/7] FIX Clone Config_LRU incl. objects in array

Caused key confusions when using Config::nest()/unnest()
---
 core/Config.php | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/core/Config.php b/core/Config.php
index 847c482d4..ad92f1cfc 100644
--- a/core/Config.php
+++ b/core/Config.php
@@ -623,6 +623,20 @@ class Config_LRU {
 		$this->indexing = array();
 	}
 
+	public function __clone() {
+		if (version_compare(PHP_VERSION, '5.3.7', '<')) {
+			// SplFixedArray causes seg faults before PHP 5.3.7
+			$cloned = array();
+		}
+		else {
+			$cloned = new SplFixedArray(self::SIZE);
+		}
+		for ($i = 0; $i < self::SIZE; $i++) {
+			$cloned[$i] = clone $this->cache[$i];
+		}
+		$this->cache = $cloned;
+	}
+
 	public function set($key, $val, $tags = array()) {
 		// Find an index to set at
 		$replacing = null;

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 5/7] 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

From 315c03872a0178bc29529ae250c6802a42b33d6e Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Wed, 27 Mar 2013 12:06:57 +0100
Subject: [PATCH 6/7] Fixed _config.php references and usage in docs

---
 docs/en/howto/customize-cms-pages-list.md |  6 +++-
 docs/en/howto/extend-cms-interface.md     | 16 +++++++----
 docs/en/reference/dataextension.md        | 34 +++++++++++------------
 docs/en/reference/member.md               | 13 +++++----
 docs/en/reference/modeladmin.md           |  8 ++++--
 docs/en/reference/siteconfig.md           |  8 ++++--
 docs/en/topics/debugging.md               | 14 +++++-----
 docs/en/topics/directory-structure.md     |  3 +-
 docs/en/topics/environment-management.md  |  2 +-
 docs/en/topics/error-handling.md          |  7 ++---
 docs/en/topics/index.md                   |  2 +-
 docs/en/topics/module-development.md      |  2 +-
 docs/en/topics/modules.md                 |  7 +++--
 docs/en/topics/rich-text-editing.md       |  4 +--
 docs/en/topics/themes.md                  |  2 +-
 docs/en/topics/versioning.md              |  9 +++---
 16 files changed, 77 insertions(+), 60 deletions(-)

diff --git a/docs/en/howto/customize-cms-pages-list.md b/docs/en/howto/customize-cms-pages-list.md
index ce7cde39c..d3bb79cd9 100644
--- a/docs/en/howto/customize-cms-pages-list.md
+++ b/docs/en/howto/customize-cms-pages-list.md
@@ -62,7 +62,11 @@ or across page types with common characteristics.
 		}
 	}
 
+Now you just need to enable the extension in your [configuration file](/topics/configuration).
+
 	// mysite/_config/config.yml
 	LeftAndMain:
 	  extensions:
-	    - NewsPageHolderCMSMainExtension
\ No newline at end of file
+	    - NewsPageHolderCMSMainExtension
+
+You're all set! Don't forget to flush the caches by appending `?flush=all` to the URL.
\ No newline at end of file
diff --git a/docs/en/howto/extend-cms-interface.md b/docs/en/howto/extend-cms-interface.md
index 827191b1d..58a0ef4bd 100644
--- a/docs/en/howto/extend-cms-interface.md
+++ b/docs/en/howto/extend-cms-interface.md
@@ -82,10 +82,12 @@ Create a new file called `mysite/code/BookmarkedPageExtension.php` and insert th
 		}
 	}
 
-Enable the extension with the following line in `mysite/_config.php`:
+Enable the extension in your [configuration file](/topics/configuration)
 
-	:::php
-	SiteTree::add_extension('BookmarkedPageExtension');
+	:::yml
+	SiteTree:
+	  extensions:
+	    - BookmarkedPageExtension
 
 In order to add the field to the database, run a `dev/build/?flush=all`.
 Refresh the CMS, open a page for editing and you should see the new checkbox.
@@ -106,10 +108,12 @@ Add the following code to a new file `mysite/code/BookmarkedLeftAndMainExtension
 		}
 	}
 	
-Enable the extension with the following line in `mysite/_config.php`:
+Enable the extension in your [configuration file](/topics/configuration)
 
-	:::php
-	LeftAndMain::add_extension('BookmarkedPagesLeftAndMainExtension');
+	:::yml
+	LeftAndMain:
+	  extensions:
+	    - BookmarkedPagesLeftAndMainExtension
 
 As the last step, replace the hardcoded links with our list from the database.
 Find the `<ul>` you created earlier in `mysite/admin/templates/LeftAndMain.ss`
diff --git a/docs/en/reference/dataextension.md b/docs/en/reference/dataextension.md
index c3fb1b3a6..1162da479 100644
--- a/docs/en/reference/dataextension.md
+++ b/docs/en/reference/dataextension.md
@@ -13,12 +13,8 @@ Your extension will need to be a subclass of `[api:DataExtension]` or the `[api:
 
 	:::php
 	<?php
-	
-	// mysite/code/CustomMember.php
-	
-	class CustomMember extends DataExtension {
-	
-	}
+	// mysite/code/MyMemberExtension.php
+	class MyMemberExtension extends DataExtension {}
 
 This defines your own extension where you can add your own functions, database fields or other properties you want.
 After you create this extension however it does not yet apply it to your object. Next you need to tell SilverStripe what
@@ -26,23 +22,27 @@ class you want to extend.
 
 ### Adding a extension to a built-in class
 
-Sometimes you will want to add extension to classes that you didn't make.  For example, you might want to add the
-ForumRole extension to the `[api:Member]` object.
+Sometimes you will want to add extension to classes that you can't cleanly subclass. 
+For example, you might want to add a `MyMemberExtension` class to the `[api:Member]` object.
 
+In order to active this extension, you'd add the following to your [config.yml](/topics/configuration).
+
+	:::yml
+	Member:
+	  extensions:
+	    - MyMemberExtension
+
+Alternatively, you can add extensions through PHP code as well (in your `config.php` file), 
+which means they can be used in conditional configuration.
 
 	:::php
-	ClassYouWantToOverride::add_extension('Your Class Name');
-
-
-For example above we want to override Member with a Custom Member so we would write the following
-
-	:::php
-	// add to mysite/_config.php	
-	Member::add_extension('CustomMember');
+	// Preferred notation: Through the Config API
+	Config::inst()->update('Member', 'extensions', array('MyMemberExtension'));
+	// Legacy notation: Through static class access
+	Member::add_extension('MyMemberExtension');
 
 ##  Implementation
 
-
 ###  Adding extra database fields
 
 Extra database fields can be added with a extension in the same manner as if they
diff --git a/docs/en/reference/member.md b/docs/en/reference/member.md
index cddf7ef59..7a5d818b3 100644
--- a/docs/en/reference/member.md
+++ b/docs/en/reference/member.md
@@ -88,19 +88,20 @@ and another subclass for the same email-address in the address-database.
 ## Member Role Extension
 
 Using inheritance to add extra behaviour or data fields to a member is limiting, because you can only inherit from 1
-class.  A better way is to use role extensions to add this behaviour.
+class. A better way is to use role extensions to add this behaviour. Add the following to your
+`[config.yml](/topics/configuration)`.
 
-	:::php
-	Member::add_extension('ForumRole');
-	// OR
-	Member::add_role('ForumRole');
+	:::yml
+	Member:
+	  extensions:
+	    - MyMemberExtension
 
 A role extension is simply a subclass of `[api:DataExtension]` that is designed to be used to add behaviour to `[api:Member]`. 
 The roles affect the entire class - all members will get the additional behaviour.  However, if you want to restrict
 things, you should add appropriate `[api:Permission::checkMember()]` calls to the role's methods.
 
 	:::php
-	class ForumRole extends DataExtension {
+	class MyMemberExtension extends DataExtension {
 	  /**
 	
 	   * Modify the field set to be displayed in the CMS detail pop-up
diff --git a/docs/en/reference/modeladmin.md b/docs/en/reference/modeladmin.md
index aa7665167..799b5f791 100644
--- a/docs/en/reference/modeladmin.md
+++ b/docs/en/reference/modeladmin.md
@@ -245,8 +245,12 @@ also another tool at your disposal: The `[api:Extension]` API.
 		}
 	}
 
-	// mysite/_config.php
-	MyAdmin::add_extension('MyAdminExtension');
+Now enable this extension through your `[config.yml](/topics/configuration)` file.
+
+	:::yml
+	MyAdmin:
+	  extensions:
+	    - MyAdminExtension
 
 The following extension points are available: `updateEditForm()`, `updateSearchContext()`,
 `updateSearchForm()`, `updateList()`, `updateImportForm`.
diff --git a/docs/en/reference/siteconfig.md b/docs/en/reference/siteconfig.md
index b63ca59a2..24b33abd4 100644
--- a/docs/en/reference/siteconfig.md
+++ b/docs/en/reference/siteconfig.md
@@ -24,7 +24,6 @@ Or if you want to access variables in the PHP you can do
 
 	:::php
 	$config = SiteConfig::current_site_config(); 
-	
 	$config->Title
 
 
@@ -49,9 +48,12 @@ Create a mysite/code/CustomSiteConfig.php file.
 	}
 
 
-Then add a link to your extension in the _config.php file like below.
+Then activate your extension in your `[config.yml](/topics/configuration)` file.
 
-	SiteConfig::add_extension('CustomSiteConfig');
+	:::yml
+	SiteConfig:
+	  extensions:
+	    - CustomSiteConfig
 
 
 This tells SilverStripe to add the CustomSiteConfig extension to the `[api:SiteConfig]` class. 
diff --git a/docs/en/topics/debugging.md b/docs/en/topics/debugging.md
index 51aa1c9b8..2d1fccd57 100644
--- a/docs/en/topics/debugging.md
+++ b/docs/en/topics/debugging.md
@@ -3,10 +3,10 @@
 ## Environment Types
 
 Silverstripe knows three different environment-types (or "debug-levels"). Each of the levels gives you different tools
-and functionality. "dev", "test" and "live". You can either configure the environment of the site in the
-mysite/_config.php file or in your [environment configuration file](/topics/environment-management).
+and functionality. "dev", "test" and "live". You can either configure the environment of the site in your
+[config.yml file](/topics/configuration) or in your [environment configuration file](/topics/environment-management).
 
-The definition of setting an environment in your `mysite/_config/config.yml` looks like
+The definition of setting an environment in your `config.yml` looks like
 
 	:::yml
 	Director:
@@ -17,7 +17,7 @@ The definition of setting an environment in your `mysite/_config/config.yml` loo
 When developing your websites, adding page types or installing modules you should run your site in devmode. In this mode
 you will be able to view full error backtraces and view the development tools without logging in as admin.
 
-To set your site to dev mode set this in your `mysite/_config/config.yml` file
+To set your site to dev mode set this in your `config.yml` file
 
 	:::yml
 	Director:
@@ -37,7 +37,7 @@ not need to use test mode if you do not have a staging environment or a place fo
 In this mode error messages are hidden from the user and it includes `[api:BasicAuth]` integration if you want to password
 protect the site.
 
-To set your site to test mode set this in your `mysite/_config/config.yml` file
+To set your site to test mode set this in your `config.yml` file
 
 	:::yml
 	Director:
@@ -45,7 +45,7 @@ To set your site to test mode set this in your `mysite/_config/config.yml` file
 
 
 A common situation is to enable password protected site viewing on your test site only. 
-You can enable that but adding this to your `mysite/_config/config.yml` file:
+You can enable that but adding this to your `config.yml` file:
 
 	:::yml
 	---
@@ -61,7 +61,7 @@ Live sites should always run in live mode. Error messages are suppressed from th
 to email the developers. This enables near real time reporting of any fatal errors or warnings on the site and can help
 find any bugs users run into.
 
-To set your site to live mode set this in your `mysite/_config/config.yml` file
+To set your site to live mode set this in your `config.yml` file
 
 	:::yml
 	Director:
diff --git a/docs/en/topics/directory-structure.md b/docs/en/topics/directory-structure.md
index 626ed1b20..32d8869f7 100644
--- a/docs/en/topics/directory-structure.md
+++ b/docs/en/topics/directory-structure.md
@@ -21,6 +21,7 @@ existing modules or the directories lists in "Core Structure".
  | Directory           | Description                                                         | 
  | ---------           | -----------                                                         | 
  | `<mysite>/`           | This directory contains all of your code that defines your website. | 
+ | `<mysite>/_config`    | YAML configuration specific to  your application                    | 
  | `<mysite>/code`       | PHP code for model and controller (subdirectories are optional)     | 
  | `<mysite>/templates`  | HTML [templates](templates) with *.ss-extension                     | 
  | `<mysite>/css `       | CSS files                                                           | 
@@ -38,7 +39,7 @@ See [themes](/topics/themes)
 
 ## Module Structure		{#module_structure}
 
-Modules are currently top-level folders that need to have a *_config.php*-file present.
+Modules are currently top-level folders that have a `_config.php` file or a `_config/` directory present.
 They should follow the same conventions as posed in "Custom Site Structure"
 
 Example Forum:
diff --git a/docs/en/topics/environment-management.md b/docs/en/topics/environment-management.md
index 431255cf3..68ff2458b 100644
--- a/docs/en/topics/environment-management.md
+++ b/docs/en/topics/environment-management.md
@@ -35,7 +35,7 @@ Create a new file, `~/Sites/_ss_environment.php`.  Put the following content in
 	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
 
 
-Now, edit each of your site's configuration file, `~/Sites/(projectname)/mysite/_config.php`.  Delete all mention
+Now, edit each of your site's configuration file, usually `mysite/_config.php`.  Delete all mention
 of `$databaseConfig` and `Director::set_dev_servers`, and instead make sure that you file starts like this.
 
 	:::php
diff --git a/docs/en/topics/error-handling.md b/docs/en/topics/error-handling.md
index 8ad12e720..c40650521 100644
--- a/docs/en/topics/error-handling.md
+++ b/docs/en/topics/error-handling.md
@@ -54,7 +54,7 @@ You can indicate a log file relative to the site root. The named file will have
 (an encoded file containing backtraces and things) will go to a file of a similar name, but with the suffix ".full"
 added.
 
-`<mysite>/_config.php`:
+`mysite/_config.php`:
 
 	:::php
 	// log errors and warnings
@@ -67,19 +67,18 @@ added.
 In addition to SilverStripe-integrated logging, it is adviseable to fall back to PHPs native logging functionality. A
 script might terminate before it reaches the SilverStripe errorhandling, for example in the case of a fatal error.
 
-`<mysite>/_config.php`:
+`mysite/_config.php`:
 
 	:::php
 	ini_set("log_errors", "On");
 	ini_set("error_log", "/my/logfile/path");
 
 
-
 ## Email Logs
 
 You can send both fatal errors and warnings in your code to a specified email-address.
 
-`<mysite>/_config.php`:
+`mysite/_config.php`:
 
 	:::php
 	// log errors and warnings
diff --git a/docs/en/topics/index.md b/docs/en/topics/index.md
index b70885bff..e6700518a 100644
--- a/docs/en/topics/index.md
+++ b/docs/en/topics/index.md
@@ -5,7 +5,7 @@ It is where most documentation should live, and is the natural "second step" aft
 
  * [Access Control and Page Security](access-control): Restricting access and setting up permissions on your website
  * [Command line Usage](commandline): Calling controllers via the command line interface using `sake`
- * [Configuring your website](configuration): How to configure the `_config.php` file
+ * [Configuration](configuration): Influence behaviour through PHP and YAML configuration
  * [Controller](controller): The intermediate layer between your templates and the data model
  * [Data Types](data-types): Types that properties on `DataObject` can have (e.g. `Text` or `Date`)
  * [Datamodel](datamodel): How we use an "Object-relational model" to expose database information in a useful way
diff --git a/docs/en/topics/module-development.md b/docs/en/topics/module-development.md
index 251784fa8..964e051d3 100644
--- a/docs/en/topics/module-development.md
+++ b/docs/en/topics/module-development.md
@@ -8,7 +8,7 @@ templating for any initial installation. If you're wanting to add generic functi
 project, like a forum, an ecommerce package or a blog you can do it like this;
 
 1.  Create another directory at the root level (same level as "framework" and "cms")
-2.  You must create an _config.php inside your module directory, else SilverStripe will not include it
+2.  You must create an `_config/` directory inside your module directory, else SilverStripe will not include it
 3.  Inside your module directory, follow our [directory structure guidelines](/topics/directory-structure#module_structure)
 
 ## Tips
diff --git a/docs/en/topics/modules.md b/docs/en/topics/modules.md
index dbe5d21c1..38115e0eb 100644
--- a/docs/en/topics/modules.md
+++ b/docs/en/topics/modules.md
@@ -7,8 +7,9 @@ directory.  In a default SilverStripe download, even resources in 'framework' an
 same as every other module.
 
 SilverStripe's `[api:ManifestBuilder]` will find any class, css or template files anywhere under the site's main
-directory.  The _config.php file in the module directory can be used to define director rules, calls to
-Object::useCustomClass(), and the like.  So, by unpacking a module into site's main directory and viewing the site with
+directory.  The `_config.php` file in the module directory as well as the [_config/*.yml files](/topics/configuration)
+can be used to define director rules, add
+extensions, etc.  So, by unpacking a module into site's main directory and viewing the site with
 ?flush=1 on the end of the URL, all the module's new behaviour will be incorporated to your site:
 
 *  You can create subclasses of base classes such as SiteTree to extend behaviour.
@@ -85,7 +86,7 @@ Github also provides archive downloads which are generated automatically for eve
 The main folder extracted from the archive
 might contain the version number or additional "container" folders above the actual module
 codebase. You need to make sure the folder name is the correct name of the module
-(e.g. "blog/" rather than "silverstripe-blog/"). This folder should contain a `_config.php` file.
+(e.g. "blog/" rather than "silverstripe-blog/"). This folder should contain a `_config/` directory.
 While the module might register and operate in other structures,
 paths to static files such as CSS or JavaScript won't work.
 </div>
diff --git a/docs/en/topics/rich-text-editing.md b/docs/en/topics/rich-text-editing.md
index 6adb4c8b0..cc9ed7ccb 100644
--- a/docs/en/topics/rich-text-editing.md
+++ b/docs/en/topics/rich-text-editing.md
@@ -25,8 +25,8 @@ functionality. It is usually added through the `[api:DataObject->getCMSFields()]
 
 To keep the JavaScript editor configuration manageable and extensible,
 we've wrapped it in a PHP class called `[api:HtmlEditorConfig]`.
-The class comes with its own defaults, which are extended through the `_config.php`
-files in the framework (and the `cms` module in case you've got that installed).
+The class comes with its own defaults, which are extended through [configuration files](/topics/configuration)
+in the framework (and the `cms` module in case you've got that installed).
 There can be multiple configs, which should always be created / accessed using `[api:HtmlEditorConfig::get]`.
 You can then set  the currently active config using `set_active()`.
 By default, a config named 'cms' is used in any field created throughout the CMS interface.
diff --git a/docs/en/topics/themes.md b/docs/en/topics/themes.md
index 8a1130443..1c266aefa 100644
--- a/docs/en/topics/themes.md
+++ b/docs/en/topics/themes.md
@@ -14,7 +14,7 @@ as a .tar.gz file.
 
 1.  Unpack the contents of the zip file into the `themes` directory in your SilverStripe installation.
 2.  Change the site to the theme. You can do this either by:
-	- Altering the `SSViewer.theme` setting in your `mysite/_config/config.yml`
+	- Altering the `SSViewer.theme` setting in your `[config.yml](/topics/configuration)`
 	- changing the theme in the Site Configuration panel in the CMS
 3. Visit your homepage with ?flush=all appended to the URL. `http://yoursite.com?flush=all`
 
diff --git a/docs/en/topics/versioning.md b/docs/en/topics/versioning.md
index c0dfc98e1..5e8d07663 100644
--- a/docs/en/topics/versioning.md
+++ b/docs/en/topics/versioning.md
@@ -20,11 +20,12 @@ It's a `[api:DataExtension]`, which allow it to be applied to any `[api:DataObje
 
 Adding versioned to your `DataObject` subclass works the same as any other extension.
 It accepts two or more arguments denoting the different "stages",
-which map to different database tables.
+which map to different database tables. Add the following to your [configuration file](/topics/configuration):
 
-	:::php
-	// mysite/_config.php
-	MyRecord::add_extension('Versioned("Stage","Live")');
+	:::yml
+	MyRecord:
+	  extensions:
+	    - Versioned("Stage","Live")
 
 Note: The extension is automatically applied to `SiteTree` class.
 

From ccb0155b8f65a00598a778a4962dc350913838d5 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Wed, 27 Mar 2013 12:08:12 +0100
Subject: [PATCH 7/7] Config docs improvement: @config and LSB mentions

Also moved some less important "notes" further down the page.
The doc is still written too much like a technical spec, we need
something that's more accessible to beginners.
---
 docs/en/topics/configuration.md | 90 +++++++++++++++++----------------
 1 file changed, 47 insertions(+), 43 deletions(-)

diff --git a/docs/en/topics/configuration.md b/docs/en/topics/configuration.md
index fe1d90b78..69ba3ca85 100644
--- a/docs/en/topics/configuration.md
+++ b/docs/en/topics/configuration.md
@@ -3,6 +3,8 @@
 ## Introduction
 
 SilverStripe 3 comes with a comprehensive code based configuration system.
+It primarily relies on declarative [YAML](http://en.wikipedia.org/wiki/YAML) files,
+and falls back to procedural PHP code, as well as PHP static variables.
 
 Configuration can be seen as separate from other forms of variables (such as per-member or per-site settings) in the
 SilverStripe system due to three properties:
@@ -15,24 +17,23 @@ In SilverStripe 3, each class has it's configuration specified as set of named p
 values at any given time are calculated by merging several sources using rules explained below. 
 These sources are as follows (in highest -> lowest priority order):
 
-  - Values set via a call to Config#update
+  - Values set via a call to `[api:Config::update()]`
   - Values taken from YAML files in specially named directories
   - Statics set on an "extra config source" class (such as an extension) named the same as the name of the property
     (optionally)
   - Statics set on the class named the same as the name of the property
   - The parent of the class (optionally)
 
-Some things to keep in mind when working with the configuration system
+Like statics, configuration values may only contain a literal or constant; neither objects nor expressions are allowed.
 
-  - Like statics, configuration values may only contain a literal or constant; neither objects nor expressions are
-    allowed
-  - The list of properties that can be set on a class is not pre-defined, and there is no way to introspect the list
-    of properties or the expected type of any property
-  - There is no way currently to restrict read or write access to any configuration property
-  - There is no way currently to mutate or intercept read or write access to any configuration property - that is
-    (for example) there is no support for getters or setters
+## Finding Configuration
 
-## The merge
+Since configuration settings are just static properties on any SilverStripe class,
+there's no exhaustive list. All configurable statics are marked with a `@config` docblock
+though, so you can search for them in the codebase. The same docblock will also contain
+a description of the configuration setting.
+
+## Customizing Configuration (through merging)
 
 Each named class configuration property can contain either an array or a non-array value.
 If the value is an array, each value in the array may also be one of those three types
@@ -57,7 +58,7 @@ the result will be the higher priority false-ish value.
 The locations that configuration values are taken from in highest -> lowest priority order are:
 
 - Any values set via a call to Config#update
-- The configuration values taken from the YAML files in _config directories (internally sorted in before / after order, where
+- The configuration values taken from the YAML files in `_config/` directories (internally sorted in before / after order, where
   the item that is latest is highest priority)
 - Any static set on an "additional static source" class (such as an extension) named the same as the name of the property
 - Any static set on the class named the same as the name of the property
@@ -69,15 +70,18 @@ They are much simpler. They consist of a list of key / value pairs. When applied
 - If the composite value is an associative array, any member of that array that matches both the key and value of any pair in the mask is removed
 - If the composite value is not an array, if that value matches any value in the mask it is removed
 
-## Reading and updating configuration via the Config class
+## Reading and updating via the Config class
 
 The Config class is both the primary manner of getting configuration values and one of the locations you can set
-configuration values
+configuration values.
+
+Note: There is no way currently to restrict read or write access to any configuration property,
+or influence/check the values being read or written.
 
 ### Global access
 
 The first thing you need to do to use the Config class is to get the singleton instance of that class. This can be
-done by calling the static method Config::inst(), like so:
+done by calling the static method `[api:Config::inst()]`, like so:
 
 	$config = Config::inst();
 
@@ -92,18 +96,18 @@ Note that there is no "set" method. Because of the merge, it is not possible to
 property (unless you're setting it to a true-ish literal). Update adds new values that are treated as the highest
 priority in the merge, and remove adds a merge mask that filters out values.
 
-### Short-hand reading and updating configuration for instances of Object children
+### Short-hand access
 
 Within any subclass of Object you can call the config() instance method to get an instance of a proxy object
 which accesses the Config class with the class parameter already set.
 
-For instance, instead of writing
+For instance, instead of writing:
 
 	:::php
 	Config::inst()->get($this->class, 'my_property');
 	Config::inst()->update($this->class, 'my_other_property', 2);
 
-You can write
+You can write:
 
 	:::php
 	$this->config()->get('my_property');
@@ -112,13 +116,18 @@ You can write
 Or even shorter:
 
 	:::php
-	$this->config()->my_property;
-	$this->config()->my_other_property = 2;
+	$this->config()->my_property; // getter
+	$this->config()->my_other_property = 2; // setter
+
+This also works statically:
+
+	MyClass::config()->my_property; // getter
+	MyClass::config()->my_property = 2; // setter
 
 ## Setting configuration via YAML files
 
 Each module can (in fact, should - see below for why) have a directory immediately underneath the main module
-directory called "_config".
+directory called `_config/`.
 
 Inside this directory you can add yaml files that contain values for the configuration system.
 
@@ -138,15 +147,12 @@ value section in the header section that immediately preceeds the value section.
 
 #### Reference paths and fragment identifiers
 
-Each value section has a reference path. Each path looks a little like a URL, and is of this form:
+Each value section has a reference path. Each path looks a little like a URL, 
+and is of this form: `module/file#fragment`.
 
-	module/file#fragment
-
-"module" is the name of the module this YAML file is in
-
-"file" is the name of this YAML file, stripped of the extension (so for routes.yml, it would be routes)
-
-"fragment" is a specified identifier. It is specified by putting a `Name: {fragment}` key / value pair into the header
+ - "module" is the name of the module this YAML file is in
+ - "file" is the name of this YAML file, stripped of the extension (so for routes.yml, it would be routes)
+ - "fragment" is a specified identifier. It is specified by putting a `Name: {fragment}` key / value pair into the header
 section. If you don't specify a name, a random one will be assigned.
 
 This reference path has no affect on the value section itself, but is how other header sections refer to this value
@@ -282,18 +288,18 @@ do not have to define a static for a property to be valid.
 ## Configuration as a module marker
 
 Configuration files also have a secondary sub-role. Modules are identified by the `[api:ManifestBuilder]` by the
-presence of a _config directory (or a _config.php file) as a top level item in the module directory.
+presence of a `_config/` directory (or a `_config.php` file) as a top level item in the module directory.
 
 Although your module may choose not to set any configuration, it must still have a _config directory to be recognised
 as a module by the `[api:ManifestBuilder]`, which is required for features such as autoloading of classes and template
 detection to work.
 
-## _config.php
+## Complex configuration through _config.php
 
-In addition to the configuration system described above, each module can provide a file called _config.php
+In addition to the configuration system described above, each module can provide a file called `_config.php`
 immediately within the module top level directory.
 
-These _config.php files will be included at initialisation, and are a useful way to set legacy configuration
+These `_config.php` files will be included at initialisation, and are a useful way to set legacy configuration
 or set configuration based on rules that are more complex than can be encoded in YAML files.
 
 However they should generally be avoided when possible, as they slow initialisation.
@@ -301,29 +307,27 @@ However they should generally be avoided when possible, as they slow initialisat
 Please note that this is the only place where you can put in procedural code - all other functionality is wrapped in
 classes (see [common-problems](/installation/common-problems)).
 
-## Constants
 
-Some constants are user-defineable within *_ss_environment.php*.
+## Configuration through the CMS
 
-## No GUI configuration
-
-SilverStripe framework does not provide a method to set configuration via a web panel
-
-This lack of a configuration-GUI is on purpose, as we'd like to keep developer-level options where they belong (into
+SilverStripe framework does not provide a method to set most system-level configuration via a web panel.
+This lack of a configuration GUI is on purpose, as we'd like to keep developer-level options where they belong (into
 code), without cluttering up the interface. See this core forum discussion ["The role of the
 CMS"](http://www.silverstripe.org/archive/show/532) for further reasoning.
 
-In addition to these principle, some settings are 
- * Author-level configuration like interface language or date/time formats can be performed in the CMS "My Profile" section (`admin/myprofile`). 
- * Group-related configuration like `[api:HTMLEditorField]` settings can be found in the "Security" section (`admin/security`).
+The GUI-based configuation is limited to the following:
+
+ * Author-level configuration like interface language or date/time formats can be performed in the CMS "My Profile" section
+ * Group-related configuration like `[api:HTMLEditorField]` settings can be found in the "Security" section
  * Site-wide settings like page titles can be set (and extended) on the root tree element in the CMS "Content" section (through the [siteconfig](/reference/siteconfig) API).
+ * Any configuration interfaces added by custom code, for example through `getCMSFields()`
 
 ## Constants and the _ss_environment.php File
 
 See [environment-management](/topics/environment-management).
 
 
-## User-level: Member-object
+## User preferences in the `Member` class
 
 All user-related preferences are stored as a property of the `[api:Member]`-class (and as a database-column in the
 *Member*-table). You can "mix in" your custom preferences by using `[api:DataObject]` for details.