From d78be1d424eb1f3ac40b0804a8eeb8d3e382a9da Mon Sep 17 00:00:00 2001
From: Damian Mooyman <damian@silverstripe.com>
Date: Fri, 6 Apr 2018 09:21:27 +1200
Subject: [PATCH] DOCS Upgrading notes for app/src folder

---
 docs/en/03_Upgrading/index.md  |  5 ++--
 docs/en/04_Changelogs/4.2.0.md | 43 ++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/docs/en/03_Upgrading/index.md b/docs/en/03_Upgrading/index.md
index cd95583e5..989eabc82 100644
--- a/docs/en/03_Upgrading/index.md
+++ b/docs/en/03_Upgrading/index.md
@@ -43,7 +43,8 @@ through the [Composer dependency update section](/changelogs/4.0.0#deps)
 * Backup your database content.
 * Backup your webroot files.
 * Download the new release and uncompress it to a temporary folder.
-* Leave custom folders like *mysite* or *themes* in place.
+* Leave custom folders like *themes* in place.
+* Rename `mysite/code` folder to `app/src`, updating your `app/_config/mysite.yml` config to set the new project name.
 * Identify system folders in your webroot (`cms`, `framework` and any additional modules).
 * Delete existing system folders (or move them outside of your webroot).
 * Add a `private static $table_name = 'MyDataObject'` for any custom DataObjects in your code that are namespaced. This ensures that your database table name will be `MyDataObject` instead of `Me_MyPackage_Model_MyDataObject` (converts your namespace to the table_name).
@@ -99,7 +100,7 @@ For a full list of renamed classes, check the `.upgrade.yml` definitions in each
 After installing, run the upgrader upgrade command: 
 ```
 cd ~/my-project-root
-~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
+~/.composer/vendor/bin/upgrade-code upgrade ./app/src --write
 ```
 
 ## Migrating files
diff --git a/docs/en/04_Changelogs/4.2.0.md b/docs/en/04_Changelogs/4.2.0.md
index db17354a6..638d69761 100644
--- a/docs/en/04_Changelogs/4.2.0.md
+++ b/docs/en/04_Changelogs/4.2.0.md
@@ -7,6 +7,49 @@
 
 ## Upgrading {#upgrading}
 
+### App folder name
+
+The standard 'mysite' code naming convention has changed in 4.2. Although existing sites can continue
+to use 'mysite/code` to store their base project code, the recommendation and new default is to
+store code in `app/src`.
+
+Additionally, we reinforce the recommendation to use psr-4 autoloading in your project to speed up
+class loading.
+
+In order to upgrade a site to use `app/src` folder:
+
+ - Rename the folder `mysite` to `app` and `code` to `src`.
+ - Update your `app/_config/mysite.yml` config to the below:
+
+```yaml
+---
+Name: myproject
+---
+SilverStripe\Core\Manifest\ModuleManifest:
+  project: app
+```
+
+ - add psr-4 for your root project files and namespace. An example `composer.json` below
+   shows how this might look:
+
+```json
+{
+    "autoload": {
+        "psr-4": {
+            "TractorCow\\MyWebsite\\": "app/src/"
+        },
+        "classmap": [
+            "app/src/Page.php",
+            "app/src/PageController.php"
+        ]
+    }
+}
+```
+
+ - Ensure you flush your site with `?flush=all`
+ 
+Note: In 5.0 the app folder will be fixed to `app` and cannot be soft-coded via `mysite.yml`
+
 ### Disable session-based stage setting
 
 When viewing a versioned record (usually pages) in "draft" mode,