DOCS finalise module upgrade guide, correct mistakes in original upgrade guide

docs/en/03_Upgrading/01_Upgrading_module.md

@@ -260,5 +260,76 @@ The public web root does not directly affect module. So you can skip this step.
 
 While SilverStripe 4 projects can get away with directly referencing static assets under some conditions, modules must dynamically exposed their static assets. This is necessary to move modules to the vendor folder and to enable the public web root.  
 
-  
- 
+### Exposing your module's static assets
+
+You'll need to update your module's `composer.json` file with a `extra.expose` key.
+
+
+```diff
+{
+    "name": "example-user/silverstripe-example-module",
+    "type": "silverstripe-vendormodule",
+    "require": {
+        "silverstripe/framework": "^4",
+        "silverstripe/vendor-plugin": "^1"
+    },
+    "autoload": {
+        "psr4": {
+            "ExampleUser\\SilverstripeExampleModule\\": "code/"
+        }
+    },
+    "autoload-dev": {
+        "psr4": {
+            "ExampleUser\\SilverstripeExampleModule\\Tests\\": "tests/"
+        }
+-    }
++    },
++    "extra": {
++        "expose": [
++            "images",
++            "styles",
++            "javascript"
++        ]
++    }
+}
+```
+
+### Referencing static assets
+
+This process is essentially the same for projects and modules. The only difference is that module static asset paths must be prefix with the module name as defined in their composer.json file.
+
+```diff
+<?php 
+- Requirements::css('silverstripe-example-module/styles/admin.css');
++ Requirements::css('example-user/silverstripe-example-module: styles/admin.css');
+$pathToImage =
+-    'silverstripe-example-module/images/logo.png';
++    ModuleResourceLoader::singleton()->resolveURL('example-user/silverstripe-example-module: images/logo.png');
+```
+
+## Step 10 - Update database class references {#step10}
+
+Just like SilverStripe projects, your module must define class names remapping for every DataObject child.
+
+```
+SilverStripe\ORM\DatabaseAdmin:
+  classname_value_remapping:
+    ExampleModuleDummyDataObject: ExampleUser\SilverstripeExampleModule\Models\DummyDataObject
+```
+
+On the first `dev/build` after a successful upgrade, the `ClassName` field on each DataObject table will be substituted with the namespaced classname.
+
+    
+## Extra steps
+
+You've been through all the steps covered in the regular project upgrade guide. These 2 additional steps might not be necessary.
+
+### Create migration tasks
+
+Depending on the nature of your module, you might need to perform additional task to complete the upgrade process. For example, the `framework` module ships with a file migration tasks that converts Files from the old SilverStripe 3 structure to the new structure required by SilverStripe 4.
+
+Extend [BuildTasks](api:SilverStripe/Dev/BuildTask) and create your own migration task if your module requires post-upgrade work. Document this clearly for your users so they know they need to run the task after they're done upgrading their project.
+
+### Keep updating your `.upgrade.yml`
+
+The upgrader can be run on project that have already been upgraded to SilverStripe 4. As you introduce new API and deprecate old ones, you can keep updating your `.upgrade.yml` file to make it easy for your users to keep their code up to date. If you do another major release of your module aimed at SilverStripe 4, you can use all the tools in the upgrader to make the upgrade process seamless for your users.

docs/en/03_Upgrading/index.md

@@ -1091,47 +1091,42 @@ For example, let's say you have `scripts`, `images` and `css` folders under `app
 For the change to take affect, run the following command: `composer vendor-expose`.
 
 ### Referencing static assets in your PHP code
-Wherever you would have use an hardcoded path, you can now use the `projectname: path/to/file.css` syntax.
-
-`projectname` is controlled by the `project` property of `SilverStripe\Core\Manifest\ModuleManifest` in your YML configuration. This configuration file should look like this:
- ```yaml  
- SilverStripe\Core\Manifest\ModuleManifest:
-   project: app
- ```
+Wherever you would have use an hardcoded path, you can now use the `path/to/file.css` syntax. To reference a static file from a module, prefix the path with the module's name (e.g.: `silverstripe/admin:client/dist/js/bundle.js`).
 
 To add some javascript and css files to your requirements from your PHP code, you could use this syntax:
 ```php
 use SilverStripe\View\Requirements;
 
 # Load your own style and scripts
-Requirements::css('app: css/styles.css');
-Requirements::script('app: scripts/client.css');
+Requirements::css('app/css/styles.css');
+Requirements::script('app/scripts/client.css');
 
 # Load some assets from a module.  
 Requirements::script('silverstripe/blog: js/main.bundle.js');
 ```
 
-You can `SilverStripe\Core\Manifest\ModuleLoader` to get the web path of file.
+You can `SilverStripe\Core\Manifest\ModuleResourceLoader` to get the web path of file.
 ```php
-ModuleLoader::getModule('app')->getResource('images/road-runner.jpg')->getRelativePath();
+ModuleResourceLoader::singleton()->resolveURL('app/images/road-runner.jpg');
+ModuleResourceLoader::singleton()->resolveURL('silverstripe/blog: js/main.bundle.js');
 ```
 
 You can use `SilverStripe\View\ThemeResourceLoader` to access files from your theme:
 ```php
-$themeFolderPath = ThemeResourceLoader::inst()->getPath('simple');
-$themesFilePath = ThemeResourceLoader::inst()->findThemedResource('css/styles.css');
+$cssResourcePath = ThemeResourceLoader::inst()->findThemedResource('css/layout.css');
+$relativeUrl = ModuleResourceLoader::singleton()->resolveURL($cssResourcePath);
 ```
 
 For classes that expect icons, you can specify theme with:
 ```php
 class ListingPage extends \Page
 {
-    private static $icon = 'app: images/sitetree_icon.png';
+    private static $icon = 'app/images/sitetree_icon.png';
 }
 
 class MyCustomModelAdmin extends \SilverStripe\Admin\ModelAdmin
 {
-    private static $menu_icon = 'app: images/modeladmin_icon.png';
+    private static $menu_icon = 'app/images/modeladmin_icon.png';
 }
 ```
 
@@ -1139,7 +1134,7 @@ class MyCustomModelAdmin extends \SilverStripe\Admin\ModelAdmin
 SS template files accept a similar format for referencing static assets. Go through your assets files and remove hardcoded references.
 
 ```html
-<img src="$ModulePath(app)/images/coyote.png" />
+<img src="$resourceURL(app/images/coyote.png)" />
 <% require css("app: css/styles.css") %>
 ```