revisions per damian, robbie

docs/en/04_Changelogs/4.0.0.md

@@ -59,7 +59,7 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
   [behat extension](https://github.com/silverstripe/silverstripe-behat-extension) for more information.
 * The `GDBackend` and `ImagickBackend` classes have been replaced by a unified `InterventionBackend` which uses the
   [intervention/image](https://github.com/intervention/image) library to power manipualations.
-* Page types and their controllers can no longer be collated in a single file
+* Page types and their controllers can should longer be collated in a single file
 
 ## <a name="upgrading"></a>Upgrading
 
@@ -93,33 +93,6 @@ For a full list of renamed classes, check the `.upgrade.yml` definitions in each
 
 The rename won't affect class-based permission codes or database table names.
 
-##### Use ::class whenever possible
-
-Prefer:
- ```php
- private static $has_one = [
-   'MyObject' => MyObject::class
- ];
- ```
- to
- 
- ```php
-private static $has_one = [
-  'MyObject' => 'My\Project\MyObject'
-];
-```
-
-##### Use Injector wherever you can
-
-This can help with reducing changes from 3.x to 4.x by allowing your code to 
-continue to use `MyClassName`, while you tell the injector what the FQ class name is:
-
-```yaml
-SilverStripe\Core\Injector\Injector:
-  MyClassName:
-    class: Me\MyModule\MyClassName # fully qualified!
-```
-
 ##### Namespaced table names
 
 Keep in mind that table names are namespaced too. To ease data migrations, use the `$table_name` config property of your `DataObject` subclasses.
@@ -158,9 +131,9 @@ field in the `SiteTree` table still contains the singular model name, e.g. `Blog
 and that when you change it to `SilverStripe\Blog\Model\BlogPost` then everything 
 works again.
 
-Luckily the `dev/build` task is configured to look for a legacy class name mapping 
+The `dev/build` task is configured to look for a legacy class name mapping 
-configuration setting and will update this for you automatically. For an example 
+configuration setting and will update this for you automatically. For an example, 
-take a look at `_config/legacy.yml` in the CMS module. The Blog module, for instance, uses 
+refer to `_config/legacy.yml` in the CMS module. The Blog module, for instance, uses 
 this:
 
 ```yaml
@@ -214,14 +187,40 @@ The upgrader will replace `BlogPost` with `SilverStripe\\Blog\\Model\BlogPost` a
 
 A better option is to replace it with `DataObject::getSchema()->tableName(BlogPost::class)` as long as the class has already been imported into your current namespace.
 
+##### Namespacing tip: use ::class whenever possible
 
+Prefer:
+ ```php
+ private static $has_one = [
+   'MyObject' => MyObject::class
+ ];
+ ```
+ to
  
+ ```php
+private static $has_one = [
+  'MyObject' => 'My\Project\MyObject'
+];
+```
+
+##### Namespacing tip: use Injector whenever possible
+
+This can help with reducing changes from 3.x to 4.x by allowing your code to 
+continue to use `MyClassName`, while you tell the injector what the FQ class name is:
+
+```yaml
+SilverStripe\Core\Injector\Injector:
+  MyClassName:
+    class: Me\MyModule\MyClassName # fully qualified!
+```
 
 #### Migrate your controllers to their own files
 
 The convention for naming controllers is now `[MyPageType]Controller`, where it used to be `[MyPageType]_Controller`. This change was made to be more compatible with the PSR-2 standards.
 
-You can still use, for example, `Page_Controller`, but you will get a deprecation notice. It is best to change it to `PageController` during your upgrade process.
+You can still use, for example, `Page_Controller`, but you will get a deprecation notice. It is 
+best to change it to `PageController` during your upgrade process. Keep in mind any modules or
+other thirdparty code that extend `PageController` are likely to assume that class exists.
 
 By default, a controller for a page type *must* reside in the same namespace as its page. To use different logic, override `SiteTree::getControllerName()`.
 
@@ -314,7 +313,7 @@ deprecated.
 <!-- before -->
 SS_Log::log('My error message', SS_Log::ERR);
 <!-- after -->
-Injector::inst()->get('Logger')->error('My error message');
+Injector::inst()->get('LoggerInterface::class')->error('My error message');
 ```
 
 If you call that multiple times in one class, you might want to add a getter