From fe5925726e73575881914c0eaaa6f6a77a11fc40 Mon Sep 17 00:00:00 2001
From: Damian Mooyman <damian@silverstripe.com>
Date: Thu, 8 Sep 2016 12:39:17 +1200
Subject: [PATCH 1/2] Restructure 4.0.0.md

---
 docs/en/04_Changelogs/4.0.0.md | 928 +++++++++++++++++----------------
 1 file changed, 472 insertions(+), 456 deletions(-)

diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index b6965543d..849b8ea2c 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -1,426 +1,65 @@
 # 4.0.0 (unreleased)
 
-## Overview
-
-### Framework
-
- * Minimum PHP version raised to 5.5.0
- * Minimum CMS browser requirement raised from Internet Explorer 8 to Internet Explorer 10
- * Deprecate `SQLQuery` in favour `SQLSelect`
- * `DataList::filter` by null now internally generates "IS NULL" or "IS NOT NULL" conditions appropriately on queries
- * `DataObject` constructor now has an additional parameter, which must be included in subclasses.
- * `DataObject::database_fields` now returns all fields on that table.
- * `DataObject::db` now returns composite fields.
- * `DataObject::ClassName` field has been refactored into a `DBClassName` type field.
- * Image manipulations have been moved into a new `[api:ImageManipulation]` trait.
- * `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead.
- * `CMSFileAddController` removed.
- * `UploadField::setAllowedFileCategories('image')` now excludes non-resizeable images. 'unresizeable_image' is
-   can be used to validate these types.
- * `Image_Backend` API now loads and saves from `AssetContainer` instances rather than local files.
- * The following File categories have been renamed: 'zip' to 'archive', 'doc' to 'document', and 'mov' to 'video'
- * `File::updateLinks` no longer takes urls as parameters. All file links are now identified either by
-   the `DataObject::ID` in a `data-fileid` property, or via shortcodes. This is necessary because file
-   urls are no longer able to identify assets.
- * Extension point `HtmlEditorField::processImage` has been removed, and moved to `Image::regenerateImageHTML`
- * `Upload::load` now stores assets directly without saving into a `File` dataobject.
- * Protected file storage is now a core Framework API. See [/developer_guides/files/file_security] for
-   more information.
- * `Object::useCustomClass` has been removed. You should use the config API with Injector instead.
- * Upgrade of TinyMCE to version 4.
- * `File` is now versioned, and should be published before they can be used on the frontend.
-   See section on [Migrating File DataObject from 3.x to 4.0](#migrating-file-dataobject-from-3x-to-40)
-   below for upgrade notes.
- * Removed `RegenerateCachedImagesTask`
- * Removed `dev/tests/` controller in favour of standard `vendor/bin/phpunit` command
- * Updated PHPUnit from 3.7 to 4.8 ([upgrade notes](https://github.com/sebastianbergmann/phpunit/wiki/Release-Announcement-for-PHPUnit-4.0.0#backwards-compatibility-issues)). 
-   Please remove any PHPUnit related `require_once()` calls (e.g. in `FeatureContext` 
-   definitions of the [behat-extension](https://github.com/silverstripe-labs/silverstripe-behat-extension) module).
-   Run `composer require --dev 'phpunit/phpunit:~4.8'` on existing projects to pull in the new dependency.
- * `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way.
- * `CMSMain` model actions have been changed:
-   * `CMSBatchAction_Delete` and `CMSMain::delete` are no longer deprecated.
-   * `CMSBatchAction_DeleteFromLive` is removed.
-   * `CMSMain.enabled_legacy_actions` config is removed.
- * `DataObject::can` has new method signature with `$context` parameter.
- * `SiteTree.alternatePreviewLink` is deprecated. Use `updatePreviewLink` instead.
- * `Injector` dependencies no longer automatically inherit from parent classes.
- * `default_cast` is now enforced on all template variables. See upgrading notes below.
- * `HTMLText` no longer enables shortcodes by default. You can specify the `db` option for
-   html fields as `HTMLText(['whitelist=meta,link'])`, or use a `ShortcodeHTMLText` as
-   a shorthand substitute.
- * `FormField->dontEscape` has been removed. Escaping is now managed on a class by class basis.
- * `HeaderField` requires a `$name` constructor argument (`new HeaderField('MyName', 'My Title')`
- * `DBString->LimitWordCountXML` removed. Use `LimitWordCount` for XML safe version.
- * `$module` parameter in `themedCSS` and `themedJavascript` removed.
- * Theme selector has been removed from SiteConfig. Please use `SSViewer.themes` config instead.
- * `CMSMain::buildbrokenlinks()` action is removed.
- * `Folder_UnusedAssetsField` is removed.
- * `UpgradeSiteTreePermissionSchemaTask` is removed.
- * `$action` parameter to `Controller::Link()` method is standardised.
- * Removed `UpgradeSiteTreePermissionSchemaTask`
- * Removed `DataList::applyFilterContext` private method
- * Search filter classes (e.g. `ExactMatchFilter`) are now registered with `Injector`
-   via a new `DataListFilter.` prefix convention.
-   see [search filter documentation](/developer_guides/model/searchfilters) for more information.
- * FormField templates no longer look in the 'forms' folder for templates.
- * Removed `TabularStyle`
- * Removed `NestedForm`
- * Removed `Config_LRU`
- * Removed `SilverStripeInjectionCreator`
- * Removed `i18n::get_translatable_modules`
- * Removed `i18nTextCollector_Writer_Php`
- * Removed `i18nSSLegacyAdapter`
- * Removed `FunctionalTest::stat`
- * Removed `LeftAndMainMarkingFilter`
- * Removed `Controller::getFormOwner`
- * Removed `EncryptAllPasswordsTask`
- * `ServiceConfigurationLocator` is now an interface now a class.
- * `i18nTextCollectorTask` merge is now true by default.
- * Removed `FieldList` methods:
-   * `getTabPathRewrites`
-   * `setTabPathRewrites`
-   * `rewriteTabPath`
- * Removed `Form` methods:
-   * `transformTo`
-   * `callfieldmethod`
-   * `single_field_required`
-   * `current_action`
-   * `set_current_action`
- * Removed `PermissionCheckboxSetField::getAssignedPermissionCodes()` (never implemented)
- * Removed `ReportAdminForm.ss` template
- * Removed `DataList::applyFilterContext` private method
-
-## New API
-
- * New filesystem abstraction including new `DBFile` database field to hold file references.
- * `ShortcodeHandler` interface to help generate standard handlers for HTML shortcodes in the editor.
- * `AssetNameGenerator` interface, including a `DefaultAssetNameGenerator` implementation, which is used to generate
-   renaming suggestions based on an original given filename in order to resolve file duplication issues.
- * `GeneratedAssetHandler` API now used to store and manage generated files (such as those used for error page
-   cache or combined files).
- * `Requirements_Minifier` API can be used to declare any new mechanism for minifying combined required files.
-   By default this api is provided by the `JSMinifier` class, but user code can substitute their own.
- * `AssetField` formfield to provide an `UploadField` style uploader for the new `DBFile` database field.
- * `AssetControlExtension` is applied by default to all DataObjects, in order to support the management
-   of linked assets and file protection.
- * `ProtectedFileController` class is used to serve up protected assets.
- * `Object` has been broken up into various traits, each of which can be added to other objects independently:
-    * `Configurable` Provides Config API helper methods
-    * `Injectable` Provides Injector API helper methods
-    * `Extensible` Allows extensions to be applied
- * Removed ability to run tests via web requests (`http://mydomain.com/dev/tests`), use the standard CLI command instead (`vendor/bin/phpunit`)
- * Removed `dev/jstests/` controller (no replacement)
- * Moved test database cleanup task from `sake dev/tests/cleanupdb` to `sake dev/tasks/CleanupTestDatabasesTask`
- * Removed `TestRunner` and `JSTestRunner` APIs
- * Removed `PhpUnitWrapper`, `PhpUnitWrapper_3_4`, `PhpUnitWrapper_3_5`, `PhpUnitWrapper_Generic`, `SapphireTestSuite` APIs
- * Removed `SapphireTest->skipTest`, use `markTestSkipped()` in a `setUp()` method instead
- * `HtmlEditorConfig` is now an abstract class, with a default implementation `TinyMCEConfig` for the built in
-   TinyMCE editor.
- * `HtmlEditorField::setEditorConfig` may now take an instance of a `HtmlEditorConfig` class, as well as a
-   standard config identifier name.
- * A lot of standard versioned API has been refactored from `SiteTree` into `Versioned` extension. Now
-   all versioned DataObjects have `canPublish()`, `canArchive()`, `canUnpublish()`, `doPublish()`, `doArchive()`
-   `doUnpublish()`, `isPublished()` and `isonDraft()` out of the box. However, `do*()` methods will no longer
-   automatically check `can*()` permissions, and must be done by usercode before invocation.
- * GridField edit form now has improved support for versioned DataObjects, with basic publishing
-   actions available when editing records.
- * `Versioned` API has some breaking changes:
-   * Versioned constructor now only allows a single string to declare whether staging is enabled or not. The
-     number of names of stages are no longer able to be specified. See below for upgrading notes for models
-     with custom stages.
-   * `reading_stage` is now `set_stage` and throws an error if setting an invalid stage.
-   * `current_stage` is now `get_stage`
-   * `getVersionedStages` is gone.
-   * `get_live_stage` is removed. Use the `Versioned::LIVE` constant instead.
-   * `getDefaultStage` is removed. Use the `Versioned::DRAFT` constant instead.
-   * `$versionableExtensions` is now `private static` instead of `protected static`
-   * `hasStages` is addded to check if an object has a given stage.
-   * `stageTable` is added to get the table for a given class and stage.
-   * Any extension declared via `versionableExtensions` config on Versioned dataobject must now 
-     `VersionableExtension` interface at a minimum. `Translatable` has been removed from default
-     `versionableExtensions`
- * `ChangeSet` and `ChangeSetItem` have been added for batch publishing of versioned dataobjects.
- * `FormAction::setValidationExempt` can be used to turn on or off form validation for individual actions
- * `DataObject.table_name` config can now be used to customise the database table for any record.
- * `DataObjectSchema` class added to assist with mapping between classes and tables.
- * Changes to `DBString` formatting:
-   * `NoHTML` is renamed to `Plain`
-   * `LimitWordCountXML` is removed. Use `LimitWordCount` instead.
-   * `BigSummary` is removed. Use `Summary` instead.
-   * Most limit methods on `DBHTMLText` now plain text rather than attempt to manipulate the underlying HTML.
-   * `FormField::Title` and `FormField::RightTitle` are now cast as plain text by default (but can be overridden).
- * `PopoverField` added to provide popup-menu behaviour in react forms (currently not available for
-   non-react forms).
- * Admin URL can now be configured via custom Director routing rule
- * Templates now use a standard template lookup system via `SSViewer::get_templates_by_class`
-   which builds a candidate list for a given class. Actual resolution of existing templates
-   for any list of candidates is actually performed by `SSViewer::chooseTemplate`
-
-### Front-end build tooling for CMS interface
-
- * Management of CMS JavaScript dependencies via [npm](https://www.npmjs.com/)
- * ES6 is now available in all core JavaScript files via [Babel](https://babeljs.io/)
- * Bundling of core JavaScript via [Browserify](http://browserify.org/)
- * CMS build tasks managed by [Gulp](http://gulpjs.com/)
-
-If you're planning to contribute to SilverStripe core, 
-you should learn how to [use the build tooling](/developer_guides/customising_the_admin_interface/cms_architecture)
-and [work with client-side dependencies](../contributing/code#working-with-client-side-dependencies). 
-Note that you don't need any of these tools for running SilverStripe or developing your own website. 
-
-### Added new front-end UI libraries
-
- * Added the following npm libraries:
-   * [react](https://www.npmjs.com/package/react)
-   * [redux](https://www.npmjs.com/package/redux)
-   * [react-router](https://github.com/reactjs/react-router)
-   * [react-router-redux](https://github.com/reactjs/react-router-redux)
-   * [react-redux](https://www.npmjs.com/package/react-redux)
-   * [react-dom](https://www.npmjs.com/package/react-dom)
-   * [isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch)
-   * [redux-thunk](https://www.npmjs.com/package/redux-thunk)
-   * [react-addons-test-utils](https://www.npmjs.com/package/react-addons-test-utils)
- * Added SilverStripeComponent base class for building React UIs
-
-### Compiling CSS
-
-[Compass](http://compass-style.org/) has been removed and css/sprite compilation is now handled with [gulp](http://gulpjs.com/) (see [Markup and Style Conventions](../developer_guides/customising_the_admin_interface/cms_architecture/#markup-and-style-conventions)).
-
-### Bootstrap CSS
-
-Bootstrap 4 Alpha.2 CSS is available in `admin/css/bootstrap`.
-
-### Changed paths of static assets
-
-All static files (images, javascript, stylesheets, fonts) used for the CMS and forms interfaces
-in `framework` and `cms` have moved locations. These assets are now placed in a `client/` subfolder,
-to account for a structural change where both javascript and styles are co-located in component-specific folders.
-This will affect you if you have used `Requirements::block()` on files in the `framework/` or `cms/` folder.
-Care should also be taken when referencing images in these folders from your own stylesheets.
-
-```
-framework/javascript       => framework/client/dist/
-framework/javascript/lang  => framework/client/lang/
-framework/images           => framework/client/dist/images/
-framework/css              => framework/client/dist/css/
-framework/scss             => framework/client/src/styles/
-admin/javascript/          => admin/client/src/
-admin/javascript/src/      => admin/client/src/legacy/ (mostly)
-admin/javascript/lang/     => admin/client/lang/
-admin/scss/                => admin/client/styles/legacy/
-admin/css/                 => admin/client/dist/css/
-admin/css/screen.css       => admin/client/dist/css/bundle.css
-admin/images/              => admin/client/dist/images/
-admin/images/sprites/src/  => admin/client/src/sprites/
-admin/images/sprites/dist/ => admin/client/dist/sprites/
-admin/font/                => admin/client/dist/font/
-```
-
-## Deprecated classes/methods
-
-### Core
- * Added the following npm libraries:
-   * Page.js
-
- * Removed the following JavaScript libraries:
-   * History.js
-
- * `debugmethods` querystring argument has been removed from debugging.
- 
- * The following ClassInfo methods are now deprecated:
-   * `ClassInfo::baseDataClass` - Use `DataObject::getSchema()->baseDataClass()` instead.
-   * `ClassInfo::table_for_object_field` - Use `DataObject::getSchema()->tableForField()` instead
-
-### ORM
-
- * `DataList::getRelation` is removed, as it was mutable. Use `DataList::applyRelation` instead, which is immutable.
-
-### ErrorPage
-
- * `ErrorPage.static_filepath` config has been removed.
- * `ErrorPage::get_filepath_for_errorcode` has been removed
- * `ErrorPage::alternateFilepathForErrorcode` extension point has been removed
-
-See notes below on upgrading extensions to the ErrorPage class
-
-### Member
-
- * `Member` Field 'RememberLoginToken' removed, replaced with 'RememberLoginHashes' has_many relationship
-
-### Assets and Filesystem
-
-The following image manipulations previously deprecated has been removed:
-
- * `Image::SetRatioSize` superceded by `Fit`
- * `Image::SetWidth` superceded by `ScaleWidth`
- * `Image::SetHeight` superceded by `ScaleHeight`
- * `Image::SetSize` superceded by `Pad`
- * `Image::PaddedImage` superceded by `Pad`
- * `Image::CroppedImage` superceded by `Fill`
- * `Image::AssetLibraryPreview` superceded by `PreviewThumbnail`
- * `Image::AssetLibraryThumbnail` superceded by `CMSThumbnail`
-
-The following `File` methods have been removed. Since there is no longer any assumed local path for any file,
-methods which dealt with such paths may no longer be relied on.
-
- * `File::deletedatabaseOnly`
- * `File::link_shortcode_handler` renamed to `handle_shortcode`
- * `File::setParentID`
- * `File::getFullPath`
- * `File::getRelativePath`
- * `File::Content` database field is removed
-
-Image manipulations have been moved out of Image.php and now available to any File or DBFile which has the
-appropriate mime types. The following file manipulations classes and methods have been removed:
-
- * `CleanImageManipulationCache` class
- * `Image_Cached` class
- * `Image::regenerateFormattedImages`
- * `Image::getGeneratedImages`
- * `Image::deleteFormattedImages`
- * `AssetAdmin::deleteunusedthumbnails`
- * `AssetAdmin::getUnusedThumbnails`
-
-Many `Folder` methods have also been removed:
-
- * `Folder::syncChildren`
- * `Folder::constructChild`
- * `Folder::addUploadToFolder`
-
-The following filesystem synchronisation methods are also removed
-
- * `Filesystem::sync`
- * `AssetAdmin::doSync`
-
-The Spyc YAML library has been removed from /thirdparty. Please load it yourself, or use the Symfony YAML component that’s automatically installed by composer.
-
-### Requirements
-
-The following methods and properties on `Requirements_Backend` have been renamed:
-
- * `Requirements_Backund::$combine_files` made protected and renamed `$combinedFiles`
- * `Requirements_Backend::$combine_js_with_min` made protected and renamed `$minifyCombinedFiles`
- * `Requirements_Backend::$write_header_comments` made protected and renamed `$writeHeaderComment`
- * `Requirements_Backend::$write_js_to_body` made protected and renamed to `$writeJavascriptToBody`
- * `Requirements_Backend::$force_js_to_bottom` renamed to `$forceJSToBottom`
- * `get_combined_files_enabled` renamed to `getCombinedFilesEnabled`
- * `set_combined_files_enabled` renamed to `setCombinedFilesEnabled`
- * `get_suffix_requirements` renamed to `getSuffixRequirements`
- * `set_suffix_requirements` renamed to `setSuffixRequirements`
- * `get_custom_scripts` renamed to `getCustomScripts`
- * `unblock_all` renamed to `unblockAll`
- * `include_in_response` renamed to `includeInResponse`
- * `combine_files` renamed to `combineFiles`
- * `get_combine_files` renamed to `getCombinedFiles`
- * `clear_combined_files` renamed to `clearCombinedFiles`
- * `process_combined_files` renamed to `processCombinedFiles`
- * `set_write_js_to_body` renamed to `setWriteJavascriptToBody`
- * `set_force_js_to_bottom` renamed to `setForceJSToBottom`
-
-New methods on `Requirements` are added to access these:
-
- * `get_minify_combined_js_files`
- * `set_minify_combined_js_files`
- * `get_force_js_to_bottom`
- * `get_write_js_to_body`
- 
-Some methods on `Requirements` have had their method signatures changed:
-
- * `includeInHTML` has had the first parameter $template removed as it was previously deprecated.
-
-And some methods on `Requirements` and `Requirements_Backend` have been removed as they are obsolete.
-
- * `delete_combined_files` (both classes)
-
-A new config `Requirements_Backend.combine_in_dev` has been added in order to allow combined files to be
-forced on during development. If this is off, combined files is only enabled in live environments.
-
-In addition, a new API for javascript files has been added to support front-end tools
-such as [browserify](http://browserify.org/) that pre-combine scripts. You can specify
-a 'provides' option to the second parameter of `Requirements::javascript` to declare
-included files.
-
-E.g.
-
-
-    :::php
-    Requirements::javascript('mysite/js/dist/bundle.js', ['provides' => [
-        'mysite/js/jquery.js'
-        'mysite/js/src/main.js',
-        'mysite/js/src/functions.js'
-    ]]);
-    
-### RestfulService
-
-* `RestfulService` has been removed. Use Guzzle instead. See Upgrading notes.
-
-### Oembed
-
-* Our self-maintained `Oembed` implementation has been removed, in favour of introducing [oscarotero/Embed](https://github.com/oscarotero/Embed) as a dependency. 
-
-
-## Upgrading
-
-### Explicit text casting is now enforced on all template variables
- 
-Now whenever a `$Variable` is used in a template, regardless of whether any casts or methods are
-suffixed to the reference, it will be cast to either an explicit DBField for that field, or
-the value declared by the `default_cast` on the parent object.
- 
-The default value of `default_cast` is `Text`, meaning that now many cases where a field was
-left un-uncoded, this will now be safely encoded via `Convert::raw2xml`. In cases where
-un-cast fields were used to place raw HTML into templates, this will now encode this until
-explicitly cast for that field.
- 
-You can resolve this in your model by adding an explicit cast to HTML for those fields.
- 
- 
-Before:
-
-
-	:::ss
-	<div>
-	$SomeHTML
-	</div>
-
-
-	:::php
-	class MyObject extends ViewableData {
-		public function getSomeHTML {
-			$title = Convert::raw2xml($this->Title);
-			return "<h1>{$title}</h1>";
-		}
-	}
-
-
-After:
-
-
-	:::ss
-	<div>
-	$SomeHTML
-	</div>
-
-
-	:::php
-	class MyObject extends ViewableData {
-		private static $casting = [
-			'SomeHTML' => 'HTMLText'
-		];
-		
-		public function getSomeHTML {
-			$title = Convert::raw2xml($this->Title);
-			return "<h1>{$title}</h1>";
-		}
-	}
-
-If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
-instead, or if used in an actual XML file use `.CDATA`.
-
-See the [Template casting](/developer_guides/templates/casting) section for specific details.
-
-### Automatically upgrading
+## Introduction
+
+This version introduces many breaking changes, which in most projects can be managed through a combination
+of automatic upgrade processes as well as manual code review. This document reviews these changes and will
+guide developers in preparing existing 3.x code for compatibility with 4.0
+
+* [Highlights of Major Changes](#overview)
+* [Upgrading Guide](#upgrading)
+  * [Standard Upgrade](#upgrading-primary)
+  * [API Specific Upgrades](#upgrading-specifics)
+* [API Changes](#api-changes)
+  * [General and Core API](#overview-general)
+  * [ORM API](#overview-orm)
+  * [Filesystem API](#overview-filesystem)
+  * [Template and Form API](#overview-template)
+* [Commit History](#commit-history)
+
+## <a name="overview"></a>Highlights of major changes
+
+* Minimum version dependencies have increased; PHP 5.5 and Internet Explorer 10 (or other modern browser)
+  is required.
+* All code earlier marked as deprecated for 4.0 has now been removed. See
+  [deprecation documentation](/contributing/release_process) for information on code deprecation.
+* All SilverStripe classes are now namespaced, and some have been renamed. This has major implications for
+  arrangement of templates, as well as other references to classes via string literals or configuration.
+  Automatic upgrading tools have been developed to cope with the bulk of these changes (see 
+  [upgrading notes](#upgrading)).
+* Asset storage has been abstracted, and a new concept of `DBFile` references via database column references
+  now exists in addition to references via the existing `File` dataobject. File security and protected files
+  are now a core feature.
+* A new front-end development process has been developed for the construction of javascript based components,
+  prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema
+  API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS
+  powered sections.
+* CMS CSS has been re-developed using bootstrap 4 as a base. See the
+  [silverstripe blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/).
+* Asset admin has been replaced with a purely ReactJS powered upgrade, and split out
+  [into a new module](https://github.com/silverstripe/silverstripe-asset-admin/)
+* Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related
+  or inter-dependent objects to be published as a single act. Dependencies between versioned objects can be
+  declared using the new ownership API, so that developers can ensure that relational consistency is
+  maintained during publishing. This new system can be managed via the new "Campaigns" CMS section.
+  See the [silverstripe blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/).
+* Template variable casting (e.g. `<h1>$Title</h1>`) is enforced by default, which will ensure safe HTML encode
+  unless explicitly opted out.
+* Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
+  search programatically through a prioritised list when resolving template and CSS file paths.
+
+## <a name="upgrading"></a>Upgrading
+
+The below sections describe how to go about updating an existing site to be prepared for upgrade to 4.0.
+Most of these upgrading tasks will involve manual code review, although in some cases there are
+some automated processes that users can run to 
+
+### <a name="upgrading-primary"></a>Standard Upgrade
+
+This section describes the processes which every project upgrading to 4.0 should follow. This should be followed
+as a standard first point of upgrade.
+
+#### Upgrade references to renamed and namespaced classes
 
 4.0 moves many classes to namespaces, and renames many methods.
 A tool is available to (semi-)automatically update your 3.x code to the new 4.0 names.
@@ -440,7 +79,7 @@ all changed project files.
 This will resolve the majority of upgrading work, but for specific changes that will
 require manual intervention, please see the below upgrading notes.
 
-### Make sure templates are in correct locations
+#### Upgrade template locations and references
 
 Templates are now much more strict about their locations. You can no longer put a template in an arbitrary
 folder and have it be found. Case is now also checked on case-sensitive filesystems.
@@ -452,15 +91,113 @@ When using `<% include %>` template tag you should continue to leave out the `In
 `<% include Sidebar %>` will match only match `Includes/Sidebar.ss`, not `Sidebar.ss`.
 Please refer to our [template syntax](/developer_guides/templates/syntax) for details.
 
-The `forms` template folder is no longer used to lookup templates for `FormField` instances.
+Core template locations have moved - if you're including or overriding these
+(e.g. for FormField templates) please adjust to the new paths. The `forms` folder
+no longer exists, and instead template locations will be placed in paths that match
+the `SilverStripe\Forms` namespace.
 
-### Update code that uses SQLQuery
+### <a name="upgrading-specifics"></a>API Specific Upgrades
+
+The below sections deal with upgrades to specific parts of various API. Projects which rely on certain
+API should be upgraded as appropriate using any of the relevant processes documented below.
+
+#### Compatibility with the new front-end building tools
+
+If you are using Requirements from 3.x then your scripts should continue to work as they did before.
+The new front-end tooling is intended only for those wishing to customise the CMS look and feel, or behaviour.
+
+Those wishing to customise the CMS should read about how to
+[customise the admin interface](/developer_guides/customising_the_admin_interface/).
+
+#### Upgrade static references to asset paths
+
+All static files (images, javascript, stylesheets, fonts) used for the CMS and forms interfaces
+in `framework` and `cms` have moved locations. These assets are now placed in a `client/` subfolder,
+to account for a structural change where both javascript and styles are co-located in component-specific folders.
+This will affect you if you have used `Requirements::block()` on files in the `framework/` or `cms/` folder.
+Care should also be taken when referencing images in these folders from your own stylesheets.
+
+`Requirements` now throws an exception then a file is not found, rather than
+failing silently, so check your `Requirements` are pointing to files that exist.
+
+```
+framework/javascript       => framework/client/dist/
+framework/javascript/lang  => framework/client/lang/
+framework/images           => framework/client/dist/images/
+framework/css              => framework/client/dist/css/
+framework/scss             => framework/client/src/styles/
+admin/javascript/          => admin/client/src/
+admin/javascript/src/      => admin/client/src/legacy/ (mostly)
+admin/javascript/lang/     => admin/client/lang/
+admin/scss/                => admin/client/styles/legacy/
+admin/css/                 => admin/client/dist/css/
+admin/css/screen.css       => admin/client/dist/css/bundle.css
+admin/images/              => admin/client/dist/images/
+admin/images/sprites/src/  => admin/client/src/sprites/
+admin/images/sprites/dist/ => admin/client/dist/sprites/
+admin/font/                => admin/client/dist/font/
+```
+
+If you're not doing this already, we suggest looking into a JavaScript bundler
+like [Browserify](http://browserify.org/), to combine JavaScript files. SilverStripe
+core is moving away from `Requirements::combine_files` in favour of Browserify as of
+4.0 and `Requirements::combine_files` is being considered for deprecation in future
+versions.
+
+#### Explicit text casting is now enforced on all template variables
+ 
+Now whenever a `$Variable` is used in a template, regardless of whether any casts or methods are
+suffixed to the reference, it will be cast to either an explicit DBField for that field, or
+the value declared by the `default_cast` on the parent object.
+ 
+The default value of `default_cast` is `Text`, meaning that now many cases where a field was
+left un-uncoded, this will now be safely encoded via `Convert::raw2xml`. In cases where
+un-cast fields were used to place raw HTML into templates, this will now encode this until
+explicitly cast for that field.
+ 
+You can resolve this in your model by adding an explicit cast to HTML for those fields.
+
+
+Before:
+
+
+	:::php
+	class MyObject extends ViewableData {
+		public function getSomeHTML {
+			$title = Convert::raw2xml($this->Title);
+			return "<h1>{$title}</h1>";
+		}
+	}
+
+
+After:
+
+
+	:::php
+	class MyObject extends ViewableData {
+		private static $casting = [
+			'SomeHTML' => 'HTMLText'
+		];
+		
+		public function getSomeHTML {
+			$title = Convert::raw2xml($this->Title);
+			return "<h1>{$title}</h1>";
+		}
+	}
+
+
+If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
+instead, or if used in an actual XML file use `.CDATA`.
+
+See the [Template casting](/developer_guides/templates/casting) section for specific details.
+
+#### Upgrade code that uses SQLQuery
 
 Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed.
 
 See the [3.2.0](3.2.0) upgrading notes for details on how existing code should be upgraded.
 
-### New asset storage mechanism
+#### New asset storage mechanism
 
 File system has been abstracted into an abstract interface. By default, the out of the box filesystem
 uses [Flysystem](http://flysystem.thephpleague.com/) with a local storage mechanism (under the assets directory).
@@ -480,7 +217,7 @@ Note that this will not allow you to utilise certain file versioning features in
 
 See [/developer_guides/files/file_management] for more information on how the new system works.
 
-### Migrating File DataObject from 3.x to 4.0
+#### Migrating File DataObject from 3.x to 4.0
 
 Since the structure of `File` dataobjects has changed, a new task `MigrateFileTask` has been added to assist
 in migration of legacy files. Migration can be invoked by either this task, or can be configured to automatically
@@ -501,7 +238,12 @@ that previously visible assets remain visible to the public site.
 If additional security or visibility rules should be applied to File dataobjects, then
 make sure to correctly extend `canView` via extensions.
 
-### Upgrade code which acts on `Image`
+Note that pre-existing security solutions for 3.x (such as
+[secure assets module](https://github.com/silverstripe/silverstripe-secureassets))
+are incompatible with core file security.
+
+
+#### Upgrade code which acts on `Image`
 
 As all image-specific manipulations has been refactored from `Image` into an `ImageManipulations` trait, which 
 is applied to both `File` and `DBFile`. These both implement a common interface `AssetContainer`, which
@@ -551,7 +293,7 @@ E.g.
 	}
 
 
-### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
+#### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
 
 In the past all that was necessary to write a `File` DataObject to the database was to ensure a physical file
 existed in the assets folder, and that the Filename of the DataObject was set to the same location.
@@ -607,7 +349,7 @@ You can disable File versioning by adding the following to your _config.php
     File::remove_extension('Versioned');
 
 
-### Upgrading code performs custom image manipulations
+#### Upgrading code performs custom image manipulations
 
 As file storage and handling has been refactored into the abstract interface, many other components which were
 once specific to Image.php have now been moved into a shared `ImageManipulation` trait. Manipulations of file content,
@@ -672,7 +414,7 @@ There are a few differences in this new API:
   A generic `manipulate` method may be used, although the callback for this method both is given, and should return,
   an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend.
 
-### Upgrading code that uses composite db fields.
+#### Upgrading code that uses composite db fields.
 
 The `CompositeDBField` interface has been replaced with an abstract class, `DBComposite`. In many cases, custom code
 that handled saving of content into composite fields can be removed, as it is now handled by the base class.
@@ -696,7 +438,7 @@ The below describes the minimum amount of effort required to implement a composi
 	}
 
 
-### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
+#### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
 
 These methods have been updated to include base fields (such as ID, ClassName, Created, and LastEdited), as
 well as composite DB fields.
@@ -713,7 +455,7 @@ when set to true (with a field name as the first parameter), will also include t
 `Table.ClassName(args)` format.
 
 
-### Update code that uses SQLQuery
+#### Upgrade code that uses SQLQuery
 
 SQLQuery is still implemented, but now extends the new SQLSelect class and has some methods
 deprecated. Previously this class was used for both selecting and deleting, but these
@@ -724,7 +466,7 @@ these references should be replaced with `SQLSelect`. Legacy code which generate
 `SQLQuery` can still communicate with new code that expects `SQLSelect` as it is a
 subclass of `SQLSelect`, but the inverse is not true.
 
-### Update code that references table names
+#### Upgrade code that references table names
 
 A major change in 4.0.0 is that now tables and class names can differ from model to model. In order to
 fix a table name, to prevent it being changed (for instance, when applying a namespace to a model)
@@ -754,7 +496,7 @@ is available to manage these mappings.
 
 See [versioned documentation](/developer_guides/model/data_model_and_orm) for more information.
 
-### Update implementations of augmentSQL
+#### Upgrade implementations of augmentSQL
 
 Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery`
 type will raise a PHP error.
@@ -785,7 +527,7 @@ After:
 	}
 
 
-### Update code that modifies the behaviour of ErrorPage
+#### Upgrade code that modifies the behaviour of ErrorPage
 
 ErrorPage has been updated to use a configurable asset backend, similar to the `AssetStore` described above.
 This replaces the `ErrorPage.static_filepath` config that was used to write local files.
@@ -826,7 +568,7 @@ E.g.
 	  extensions:
 	    - MyErrorPageExtension
 
-### Upgrading asset web.config, .htaccess, or other server configuration
+#### Upgrading asset web.config, .htaccess, or other server configuration
 
 Server configuration files for `/assets` are no longer static, and are regenerated via a set of
 standard silverstripe templates on flush. These templates include:
@@ -843,7 +585,7 @@ If upgrading from an existing installation, make sure to invoke `?flush=all` at
 
 See [/developer_guides/files/file_security] for more information.
 
-### `ListboxField` is now multiple-only
+#### `ListboxField` is now multiple-only
 
 Previously, this field would operate as either a single select (default) or multi-select by setting
 `setMultiple` to either true or false.
@@ -851,21 +593,13 @@ Previously, this field would operate as either a single select (default) or mult
 Now this field should only be used for multi-selection. Single-selection should be done using
 a regular `DropdownField`.
 
-### `GroupedDropdownField::setDisabled` now only accepts a list of values.
+#### `GroupedDropdownField::setDisabled` now only accepts a list of values.
 
 Where previously you could specify a list of grouped values in the same way as `setSource`, this
 method now only accepts either a non-associative array of values (not titles) or an `SS_List`
 of items to disable.
 
-### Upgrading Requirements file paths
-
-`Requirements` now throws an exception then a file is not found, rather than failing silently, so check your `Requirements` are pointing to files that exist.
-
-Core JavaScript files paths have changed, so if you're referencing these, you'll have to update your file paths. Files previously in `admin/javascript` are now located in `admin/javascript/dist` and files previously located in `javascript` are now locatied in `javascript/dist`.
-
-If you're not doing this already, we suggest looking into a JavaScript bundler like [Browserify](http://browserify.org/), to combine JavaScript files. SilverStripe core is moving away from `Requirements::combine_files` in favour of Browserify as of 4.0 and `Requirements::combine_files` is being considered for deprecation in future versions.
-
-### Upgrading TinyMCE to 4.0
+#### Upgrading TinyMCE to 4.0
 
  Please see the [tinymce upgrading guide](http://archive.tinymce.com/wiki.php/Tutorial:Migration_guide_from_3.x)
  to assist with upgrades to customisations to tinymce 3.
@@ -907,7 +641,7 @@ has been removed from core. You can configure the built-in `charmap` plugin inst
 For more information on available options and plugins please refer to the
 [tinymce documentation](https://www.tinymce.com/docs/configure/)
 
-### Upgrading DataObjects with the `Versioned` extension
+#### Upgrading DataObjects with the `Versioned` extension
 
 In most cases, versioned models with the default versioning parameters will not need to be changed. However,
 there are now additional restrictions on the use of custom stage names.
@@ -950,7 +684,7 @@ These methods are deprecated:
  * `Versioned::publish` Replaced by `Versioned::copyVersionToStage`
  * `Versioned::doPublish` Replaced by `Versioned::publishRecursive`
 
-### Implementation of ownership API
+#### Implementation of ownership API
 
 In order to support the recursive publishing of dataobjects, a new API has been developed to allow
 developers to declare dependencies between objects. See the
@@ -958,7 +692,7 @@ developers to declare dependencies between objects. See the
 
 By default all versioned dataobjects will automatically publish objects that they own.
 
-### ChangeSet batch publishing
+#### ChangeSet batch publishing
 
 ChangeSet objects have been added, which allow groups of objects to be published in
 a single atomic transaction.
@@ -966,7 +700,7 @@ a single atomic transaction.
 This API will utilise the ownership API to ensure that changes to any object include
 all necessary changes to owners or owned entities within the same changeset.
 
-### New `[image]` shortcode in `HTMLText` fields
+#### New `[image]` shortcode in `HTMLText` fields
 
 The new Ownership API relies on relationships between objects.
 Many of these relationships are already made explicit through `has_one`, `has_many` and `many_many`.
@@ -976,7 +710,7 @@ of the `Image` record rather than its path on the filesystem. The shortcode will
 when the field is rendered. Newly inserted images will automatically receive the shortcode and ownership tracking,
 and existing `<img>` will continue to work.  
 
-### Upgrading references to DBField and subclasses
+#### Upgrading references to DBField and subclasses
 
 A major change in 4.0 is the introduction of namespaced DBField subclasses. Now as a standard, all DBField subclasses have a `DB` prefix, are namespaced, and have an associative alias which omits the DB prefix.
 
@@ -1022,7 +756,7 @@ Will become:
 
 Note that string references to SS_Datetime passed to injector, or used in config values, will still work, and will refer to the updated class names.
 
-### Upgrading from deprecated RestfulService
+#### Upgrading from deprecated RestfulService
 
 Install Guzzle to get an API consuming library.
 `composer require guzzlehttp/guzzle` or add `guzzlehttp/guzzle: "^6.0"` to your composer.json.
@@ -1031,16 +765,298 @@ For information on how to use Guzzle, please see the extensive [Guzzle documenta
 
 In case you want to keep using RestfulService, you can use `Firesphere/silverstripe-restfulservice`, but it is unmaintained and deprecated.
 
-### Upgrading from deprecated Oembed
+#### Upgrading from deprecated Oembed
 
 Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding. 
 
 If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero.
 
-### Admin URL can now be configured via custom Director routing rule
+#### Admin URL can now be configured via custom Director routing rule
 
 The default `admin/` URL to access the CMS interface can now be changed via a custom Director routing rule for 
 `AdminRootController`. If your website or module has hard coded `admin` URLs in PHP, templates or JavaScript, make sure 
 to update those with the appropriate function or config call. See 
 [CMS architecture](/developer_guides/customising_the_admin_interface/cms-architecture#the-admin-url) for language 
-specific functions.
\ No newline at end of file
+specific functions.
+
+## <a name="api-changes"></a>API Changes
+
+### <a name="overview-general"></a>General and Core API
+
+#### <a name="overview-general-api"></a>General and Core API Additions / Changes
+
+* Minimum PHP version raised to 5.5.0
+* Minimum CMS browser requirement raised from Internet Explorer 8 to Internet Explorer 10
+* Updated PHPUnit from 3.7 to 4.8 ([upgrade notes](https://github.com/sebastianbergmann/phpunit/wiki/Release-Announcement-for-PHPUnit-4.0.0#backwards-compatibility-issues)). 
+  Please remove any PHPUnit related `require_once()` calls (e.g. in `FeatureContext` 
+  definitions of the [behat-extension](https://github.com/silverstripe-labs/silverstripe-behat-extension) module).
+  Run `composer require --dev 'phpunit/phpunit:~4.8'` on existing projects to pull in the new dependency.
+* Admin URL can now be configured via custom Director routing rule
+* `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead.
+* `Object::useCustomClass` has been removed. You should use the config API with Injector instead.
+* `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way.
+* `ServiceConfigurationLocator` is now an interface not a class.
+* `i18nTextCollectorTask` merge is now true by default.
+* `Object` has been broken up into various traits, each of which can be added to other objects independently:
+  * `Configurable` Provides Config API helper methods
+  * `Injectable` Provides Injector API helper methods
+  * `Extensible` Allows extensions to be applied
+* `SiteTree.alternatePreviewLink` is deprecated. Use `updatePreviewLink` instead.
+* `Injector` dependencies no longer automatically inherit from parent classes.
+* `$action` parameter to `Controller::Link()` method is standardised.
+* Moved test database cleanup task from `sake dev/tests/cleanupdb` to `sake dev/tasks/CleanupTestDatabasesTask`
+
+#### <a name="overview-general-removed"></a>General and Core Removed API
+
+* `CMSMain::buildbrokenlinks()` action is removed.
+* `SS_Log::add_writer()` method is removed.
+* Removed `CMSBatchAction_Delete`
+* Removed `CMSBatchAction_DeleteFromLive`
+* Removed `CMSMain.enabled_legacy_actions` config.
+* Removed ability to run tests via web requests (`http://mydomain.com/dev/tests`), use the standard CLI
+  command instead (`vendor/bin/phpunit`).
+* Removed `dev/jstests/` controller (no replacement)
+* Removed `TestRunner` and `JSTestRunner` APIs
+* Removed `PhpUnitWrapper`, `PhpUnitWrapper_3_4`, `PhpUnitWrapper_3_5`, `PhpUnitWrapper_Generic`, `SapphireTestSuite` APIs
+* Removed `SapphireTest::skipTest()`, use `markTestSkipped()` in a `setUp()` method instead
+* Removed the `History.js` javascript library.
+* `debugmethods` querystring argument has been removed from debugging.
+* `ErrorPage.static_filepath` config has been removed.
+* `ErrorPage::get_filepath_for_errorcode` has been removed
+* `ErrorPage::alternateFilepathForErrorcode` extension point has been removed
+* Removed `Config_LRU`
+* Removed `SilverStripeInjectionCreator`
+* Removed `i18n::get_translatable_modules` method.
+* Removed `i18nTextCollector_Writer_Php`
+* Removed `i18nSSLegacyAdapter`
+* Removed `FunctionalTest::stat`
+* Removed `LeftAndMainMarkingFilter`
+* Removed `Controller::getFormOwner`
+* The Spyc YAML library has been removed from /thirdparty. Please load it yourself, or use the
+  Symfony YAML component that’s automatically installed by composer.
+* `RestfulService` has been removed. Use Guzzle instead. See Upgrading notes.
+* Our self-maintained `Oembed` implementation has been removed, in favour of introducing
+  [oscarotero/Embed](https://github.com/oscarotero/Embed) as a dependency.
+  
+#### <a name="overview-general-deprecated"></a>General and Core Deprecated API
+
+A very small number of methods were chosen for deprecation, and will be removed in 5.0 rather than 4.0
+
+* `ClassInfo::baseDataClass` - Use `DataObject::getSchema()->baseDataClass()` instead.
+* `ClassInfo::table_for_object_field` - Use `DataObject::getSchema()->tableForField()` instead
+
+### <a name="overview-orm"></a>ORM API
+
+#### <a name="overview-orm-api"></a>ORM API Additions / Changes
+
+* Deprecate `SQLQuery` in favour `SQLSelect`
+* `DataList::filter` by null now internally generates "IS NULL" or "IS NOT NULL" conditions appropriately on queries
+* `DataObject` constructor now has an additional parameter, which must be included in subclasses.
+* `DataObject::database_fields` now returns all fields on that table.
+* `DataObject::db` now returns composite fields.
+* `DataObject::ClassName` field has been refactored into a `DBClassName` type field.
+* `DataObject::can` has new method signature with `$context` parameter.
+* `DBHTMLText` no longer enables shortcodes by default. Two injector aliases have been created for this
+  class which can be used to select the correct behaviour:
+  * `HTMLText`: `DBHTMLText` with shortcodes enabled
+  * `HTMLFragment`: `DBHTMLText` without shortcodes enabled (as default)
+* Changes to `DBString` formatting:
+  * `NoHTML` is renamed to `Plain`
+  * `LimitWordCountXML` is removed. Use `LimitWordCount` instead.
+  * `BigSummary` is removed. Use `Summary` instead.
+  * Most limit methods on `DBHTMLText` now plain text rather than attempt to manipulate the underlying HTML.
+  * `FormField::Title` and `FormField::RightTitle` are now cast as plain text by default (but can be overridden).
+* Removed `DataList::applyFilterContext` private method
+* Search filter classes (e.g. `ExactMatchFilter`) are now registered with `Injector`
+  via a new `DataListFilter.` prefix convention.
+  see [search filter documentation](/developer_guides/model/searchfilters) for more information.
+* `Versioned` API has some breaking changes:
+  * Versioned constructor now only allows a single string to declare whether staging is enabled or not. The
+    number of names of stages are no longer able to be specified. See below for upgrading notes for models
+    with custom stages.
+  * `reading_stage` is now `set_stage` and throws an error if setting an invalid stage.
+  * `current_stage` is now `get_stage`
+  * `getVersionedStages` is gone.
+  * `get_live_stage` is removed. Use the `Versioned::LIVE` constant instead.
+  * `getDefaultStage` is removed. Use the `Versioned::DRAFT` constant instead.
+  * `$versionableExtensions` is now `private static` instead of `protected static`
+  * `hasStages` is addded to check if an object has a given stage.
+  * `stageTable` is added to get the table for a given class and stage.
+  * Any extension declared via `versionableExtensions` config on Versioned dataobject must now 
+    `VersionableExtension` interface at a minimum. `Translatable` has been removed from default
+    `versionableExtensions`
+* A lot of standard versioned API has been refactored from `SiteTree` into `Versioned` extension. Now
+  all versioned DataObjects have `canPublish()`, `canArchive()`, `canUnpublish()`, `doPublish()`, `doArchive()`
+  `doUnpublish()`, `isPublished()` and `isonDraft()` out of the box. However, `do*()` methods will no longer
+  automatically check `can*()` permissions, and must be done by usercode before invocation.
+* `ChangeSet` and `ChangeSetItem` have been added for batch publishing of versioned dataobjects.
+* `DataObject.table_name` config can now be used to customise the database table for any record.
+* `DataObjectSchema` class added to assist with mapping between classes and tables.
+ 
+#### <a name="overview-orm-removed"></a>ORM Removed API
+
+* Removed `DataList::getRelation`, as it was mutable. Use `DataList::applyRelation` instead, which is immutable.
+* Removed `DataList::applyFilterContext` private method
+* `Member` Field 'RememberLoginToken' removed, replaced with 'RememberLoginHashes' has_many relationship
+* Removed `UpgradeSiteTreePermissionSchemaTask`
+* Removed `EncryptAllPasswordsTask`
+* Removed `DBString::LimitWordCountXML()` method. Use `LimitWordCount` for XML safe version.
+ 
+### <a name="overview-filesystem"></a>Filesystem API
+
+#### <a name="overview-filesystem-api"></a>Filesystem API Additions / Changes
+
+* Image manipulations have been moved into a new `[api:ImageManipulation]` trait.
+* `CMSFileAddController` removed.
+* `UploadField::setAllowedFileCategories('image')` now excludes non-resizeable images. 'unresizeable_image' is
+  can be used to validate these types.
+* `Image_Backend` API now loads and saves from `AssetContainer` instances rather than local files.
+* The following File categories have been renamed: 'zip' to 'archive', 'doc' to 'document', and 'mov' to 'video'
+* `File::updateLinks` no longer takes urls as parameters. All file links are now identified either by
+  the `DataObject::ID` in a `data-fileid` property, or via shortcodes. This is necessary because file
+  urls are no longer able to identify assets.
+* Extension point `HtmlEditorField::processImage` has been removed, and moved to `Image::regenerateImageHTML`
+* `Upload::load` now stores assets directly without saving into a `File` dataobject.
+* Protected file storage is now a core Framework API. See [/developer_guides/files/file_security] for
+  more information.
+* `File` is now versioned, and should be published before they can be used on the frontend.
+  See section on [Migrating File DataObject from 3.x to 4.0](#migrating-file-dataobject-from-3x-to-40)
+  below for upgrade notes.
+* New filesystem abstraction including new `DBFile` database field to hold file references.
+* `ShortcodeHandler` interface to help generate standard handlers for HTML shortcodes in the editor.
+* `AssetNameGenerator` interface, including a `DefaultAssetNameGenerator` implementation, which is used to generate
+  renaming suggestions based on an original given filename in order to resolve file duplication issues.
+* `GeneratedAssetHandler` API now used to store and manage generated files (such as those used for error page
+  cache or combined files).
+* `Requirements_Minifier` API can be used to declare any new mechanism for minifying combined required files.
+  By default this api is provided by the `JSMinifier` class, but user code can substitute their own.
+* `AssetField` formfield to provide an `UploadField` style uploader for the new `DBFile` database field.
+* `AssetControlExtension` is applied by default to all DataObjects, in order to support the management
+  of linked assets and file protection.
+* `ProtectedFileController` class is used to serve up protected assets.
+
+#### <a name="overview-filesystem-removed"></a>Filesystem removed API
+
+The following image manipulations previously deprecated has been removed:
+
+* `Image::SetRatioSize` superceded by `Fit`
+* `Image::SetWidth` superceded by `ScaleWidth`
+* `Image::SetHeight` superceded by `ScaleHeight`
+* `Image::SetSize` superceded by `Pad`
+* `Image::PaddedImage` superceded by `Pad`
+* `Image::CroppedImage` superceded by `Fill`
+* `Image::AssetLibraryPreview` superceded by `PreviewThumbnail`
+* `Image::AssetLibraryThumbnail` superceded by `CMSThumbnail`
+
+The following `File` methods have been removed. Since there is no longer any assumed local path for any file,
+methods which dealt with such paths may no longer be relied on.
+
+* `File::deletedatabaseOnly`
+* `File::link_shortcode_handler` renamed to `handle_shortcode`
+* `File::setParentID`
+* `File::getFullPath`
+* `File::getRelativePath`
+* `File::Content` database field is removed
+
+Image manipulations have been moved out of Image.php and now available to any File or DBFile which has the
+appropriate mime types. The following file manipulations classes and methods have been removed:
+
+* `Image_Cached` class
+* `Image::regenerateFormattedImages` method
+* `Image::getGeneratedImages` method
+* `Image::deleteFormattedImages` method
+* `AssetAdmin::deleteunusedthumbnails` method
+* `AssetAdmin::getUnusedThumbnails` method
+
+Many `Folder` api have also been removed:
+
+* `Folder_UnusedAssetsField` class
+* `Folder::syncChildren` method
+* `Folder::constructChild` method
+* `Folder::addUploadToFolder` method
+
+The following filesystem synchronisation methods and tasks are also removed
+
+* `RegenerateCachedImagesTask` class
+* `CleanImageManipulationCache` class
+* `Filesystem::sync` method
+* `AssetAdmin::doSync` method
+
+### <a name="overview-template"></a>Template and Form API
+
+#### <a name="overview-template-api"></a>Template and Form API Additions / Changes
+
+* Upgrade of TinyMCE to version 4.
+* Templates now use a standard template lookup system via `SSViewer::get_templates_by_class`
+  which builds a candidate list for a given class. Actual resolution of existing templates
+  for any list of candidates is actually performed by `SSViewer::chooseTemplate`
+* `HtmlEditorConfig` is now an abstract class, with a default implementation `TinyMCEConfig` for the built in
+  TinyMCE editor.
+* `HtmlEditorField::setEditorConfig` may now take an instance of a `HtmlEditorConfig` class, as well as a
+  standard config identifier name.
+* `HeaderField` requires a `$name` constructor argument (`new HeaderField('MyName', 'My Title')`
+* `default_cast` is now enforced on all template variables. See upgrading notes below.
+* FormField templates no longer look in the 'forms' folder for templates. As all form fields are
+  now namespaced, the path for these templates will now match the namespace of the given class instead.
+* `$module` parameter in `themedCSS` and `themedJavascript` removed.
+* Theme selector has been removed from SiteConfig. Please use `SSViewer.themes` config instead.
+* `FormAction::setValidationExempt` can be used to turn on or off form validation for individual actions
+* GridField edit form now has improved support for versioned DataObjects, with basic publishing
+  actions available when editing records.
+* `PopoverField` added to provide popup-menu behaviour in react forms (currently not available for
+  non-react forms).
+  
+The following methods and properties on `Requirements_Backend` have been renamed:
+
+* `Requirements_Backund::$combine_files` made protected and renamed `$combinedFiles`
+* `Requirements_Backend::$combine_js_with_min` made protected and renamed `$minifyCombinedFiles`
+* `Requirements_Backend::$write_header_comments` made protected and renamed `$writeHeaderComment`
+* `Requirements_Backend::$write_js_to_body` made protected and renamed to `$writeJavascriptToBody`
+* `Requirements_Backend::$force_js_to_bottom` renamed to `$forceJSToBottom`
+* `get_combined_files_enabled` renamed to `getCombinedFilesEnabled`
+* `set_combined_files_enabled` renamed to `setCombinedFilesEnabled`
+* `get_suffix_requirements` renamed to `getSuffixRequirements`
+* `set_suffix_requirements` renamed to `setSuffixRequirements`
+* `get_custom_scripts` renamed to `getCustomScripts`
+* `unblock_all` renamed to `unblockAll`
+* `include_in_response` renamed to `includeInResponse`
+* `combine_files` renamed to `combineFiles`
+* `get_combine_files` renamed to `getCombinedFiles`
+* `clear_combined_files` renamed to `clearCombinedFiles`
+* `process_combined_files` renamed to `processCombinedFiles`
+* `set_write_js_to_body` renamed to `setWriteJavascriptToBody`
+* `set_force_js_to_bottom` renamed to `setForceJSToBottom`
+
+New methods on `Requirements` are added to access these:
+
+* `get_minify_combined_js_files`
+* `set_minify_combined_js_files`
+* `get_force_js_to_bottom`
+* `get_write_js_to_body`
+ 
+Some methods on `Requirements` have had their method signatures changed:
+
+* `includeInHTML` has had the first parameter $template removed as it was previously deprecated.
+
+A new config `Requirements_Backend.combine_in_dev` has been added in order to allow combined files to be
+forced on during development. If this is off, combined files is only enabled in live environments.
+
+#### <a name="overview-template-removed"></a>Template and Form Removed API
+
+* Removed `TabularStyle`
+* Removed `NestedForm`
+* Removed `FieldList` methods:
+  * `getTabPathRewrites`
+  * `setTabPathRewrites`
+  * `rewriteTabPath`
+* Removed `Form` methods:
+  * `transformTo`
+  * `callfieldmethod`
+  * `single_field_required`
+  * `current_action`
+  * `set_current_action`
+* Removed `ReportAdminForm.ss` template
+* `FormField::dontEscape()` has been removed. Escaping is now managed on a class by class basis.
+* Removed `PermissionCheckboxSetField::getAssignedPermissionCodes()` (never implemented)
+* `Requirements::delete_combined_files()` and `Requirements::delete_combined_files()` methods have been removed
+ as they are obsolete.

From 97c2baedeb96c945265d0520788d8959e2def2fd Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Fri, 9 Sep 2016 13:33:52 +1200
Subject: [PATCH 2/2] Less verbosity in upgrading guide

---
 docs/en/04_Changelogs/4.0.0.md | 46 ++++++++++------------------------
 1 file changed, 13 insertions(+), 33 deletions(-)

diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index 849b8ea2c..4057e7f90 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -34,15 +34,14 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
   prominently featuring ReactJS to develop highly functional CMS content areas. A new standard form schema
   API has been developed to allow back-end PHP constructed forms to scaffold themselves within ReactJS
   powered sections.
-* CMS CSS has been re-developed using bootstrap 4 as a base. See the
-  [silverstripe blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/).
+* CMS CSS has been re-developed using bootstrap 4 as a base 
+  ([blog post](https://www.silverstripe.org/blog/a-frameworks-framework-why-silverstripe-4-will-use-bootstrap/))
 * Asset admin has been replaced with a purely ReactJS powered upgrade, and split out
-  [into a new module](https://github.com/silverstripe/silverstripe-asset-admin/)
+  module called [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin/). You'll need to add this to your `composer.json` to retain file management capabilities for your CMS authors.
 * Versioning is now a much more powerful feature, with the addition of campaigns to allow batches of related
   or inter-dependent objects to be published as a single act. Dependencies between versioned objects can be
   declared using the new ownership API, so that developers can ensure that relational consistency is
-  maintained during publishing. This new system can be managed via the new "Campaigns" CMS section.
-  See the [silverstripe blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/).
+  maintained during publishing. This new system can be managed via the new "Campaigns" CMS section ([blog post](https://www.silverstripe.org/blog/campaigns-in-silverstripe-4/))
 * Template variable casting (e.g. `<h1>$Title</h1>`) is enforced by default, which will ensure safe HTML encode
   unless explicitly opted out.
 * Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
@@ -187,15 +186,11 @@ After:
 
 
 If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
-instead, or if used in an actual XML file use `.CDATA`.
-
-See the [Template casting](/developer_guides/templates/casting) section for specific details.
+instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
 
 #### Upgrade code that uses SQLQuery
 
-Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed.
-
-See the [3.2.0](3.2.0) upgrading notes for details on how existing code should be upgraded.
+Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed (check the [3.2.0](3.2.0) upgrading notes).
 
 #### New asset storage mechanism
 
@@ -215,7 +210,7 @@ Note that this will not allow you to utilise certain file versioning features in
 	  legacy_paths: true
 
 
-See [/developer_guides/files/file_management] for more information on how the new system works.
+See our ["File Management" guide](/developer_guides/files/file_management) for more information.
 
 #### Migrating File DataObject from 3.x to 4.0
 
@@ -301,7 +296,6 @@ existed in the assets folder, and that the Filename of the DataObject was set to
 Since the storage of physical files is no longer a standard location, it's necessary to delegate the writing of such
 files to the asset persistence layer. As a wrapper for an individual file, you can use any of the `setFrom*`
 methods to assign content from a local (e.g. temporary) file, a stream, or a string of content.
-
 You would need to upgrade your code as below.
 
 Before:
@@ -357,7 +351,6 @@ which are used to generate what are now called "variants" of assets, is now a ge
 and `DBFile` classes through this trait.
 
 Custom manipulations, applied via extensions, must be modified to use the new API.
-
 For instance, code which sizes images to a fixed width should be updated as below:
 
 Before:
@@ -378,9 +371,7 @@ Before:
 	Image::add_extension('MyImageExtension');
 
 
-Now image manipulations are implemented with a single method via a callback generator.
-
-After:
+Now image manipulations are implemented with a single method via a callback generator:
 
 
 	:::php
@@ -444,8 +435,7 @@ These methods have been updated to include base fields (such as ID, ClassName, C
 well as composite DB fields.
 
 `DataObject::database_fields` does not have a second parameter anymore, and can be called directly on an object
-or class. E.g. `Member::database_fields()`
-
+or class. E.g. `Member::database_fields()`.
 If user code requires the list of fields excluding base fields, then use custom_database_fields instead, or
 make sure to call `unset($fields['ID']);` if this field should be excluded.
 
@@ -481,7 +471,7 @@ the `table_name` config can be applied to any DataObject class.
 
 
 In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service
-is available to manage these mappings.
+is available to manage these mappings (see [versioned documentation](/developer_guides/model/data_model_and_orm)).
 
 
 	:::php
@@ -494,15 +484,11 @@ is available to manage these mappings.
 	}
 
 
-See [versioned documentation](/developer_guides/model/data_model_and_orm) for more information.
-
 #### Upgrade implementations of augmentSQL
 
 Since this method now takes a `SQLSelect` as a first parameter, existing code referencing the deprecated `SQLQuery`
 type will raise a PHP error.
 
-E.g.
-
 Before:
 
 	:::php
@@ -547,8 +533,6 @@ In case that user code must customise this filename, such as for extensions whic
 for any error page, the extension point `updateErrorFilename` can be used. This extension point should
 also be used to replace any `alternateFilepathForErrorcode` used.
 
-E.g.
-
 
 	:::php
 	class MyErrorPageExtension extends SiteTreeExtension {
@@ -583,7 +567,7 @@ configuration customisation is done via overriding these templates.
 
 If upgrading from an existing installation, make sure to invoke `?flush=all` at least once.
 
-See [/developer_guides/files/file_security] for more information.
+See our ["File Security" guide](/developer_guides/files/file_security) for more information.
 
 #### `ListboxField` is now multiple-only
 
@@ -650,8 +634,6 @@ Rather than declaring the list of stages a model has, the constructor for `Versi
 parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively
 if it only has versioning without staging.
 
-For instance:
-
 
 	:::php
 	/**
@@ -696,7 +678,6 @@ By default all versioned dataobjects will automatically publish objects that the
 
 ChangeSet objects have been added, which allow groups of objects to be published in
 a single atomic transaction.
-
 This API will utilise the ownership API to ensure that changes to any object include
 all necessary changes to owners or owned entities within the same changeset.
 
@@ -718,7 +699,7 @@ This means that for the most part, code that worked in 3.0 won't need to be chan
 
 An exception to this is any classes which once had the `SS_` prefix, which will now be instead prefixed with `DB`, and have an un-aliased prefix. For example `SS_Datetime` is now `DBDateTime`, and has the alias `DateTime` which may be used in config.
 
-For example:
+Before:
 
 	class MyObject extends DataObject {
 	    private static $db = array(
@@ -735,7 +716,7 @@ For example:
 	    }
 	}
 
-Will become:
+After:
 
 	use SilverStripe\ORM\FieldType\DBVarchar;
 
@@ -768,7 +749,6 @@ In case you want to keep using RestfulService, you can use `Firesphere/silverstr
 #### Upgrading from deprecated Oembed
 
 Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding. 
-
 If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero.
 
 #### Admin URL can now be configured via custom Director routing rule