Merge pull request #9964 from creative-commoners/pulls/4.8/graphql-changelog-tweaks

DOC Tweak GraphQL changelog

docs/en/04_Changelogs/4.8.0.md

@@ -53,48 +53,57 @@ We have provided a high-level severity rating of the vulnerabilities below based
 ### Support for silverstripe/graphql v4 {#graphql-v4}
 
 The [silverstripe/graphql](http://github.com/silverstripe/silverstripe-graphql/issues) module is used
-to drive various parts of the CMS UI, as well as building your own GraphQL APIs in Silverstripe projects.
+to drive various parts of the CMS UI, as well as to build your own GraphQL APIs in your Silverstripe CMS projects.
+
+The CMS currently ships with `silverstripe/graphql:^3.5`, which is stable but slow for larger schemas.
+The module was rewritten from scratch with performance in mind.
+
+If you want to learn more about the development of `silverstripe/graphql` v4:
+- review [Epic: Scaling decoupled CMS usage (GraphQL performance)](https://github.com/silverstripe/silverstripe-framework/issues/8824) to better understand the goals
+- look at the [`silverstripe/graphql` pull requests](https://github.com/silverstripe/silverstripe-graphql/pulls) to see exactly what has changed.
 
-The CMS currently ships with `silverstripe/graphql:^3`, which is stable but slow for larger schemas.
-The module was rewritten from scratch with performance in mind
-(see [goals](https://github.com/silverstripe/silverstripe-framework/issues/8824) and [pull request](https://github.com/silverstripe/silverstripe-graphql/pulls)).
 The resulting`silverstripe/graphql:^4` release is currently in an alpha stage.
-We encourage everyone to get started, read our new [GraphQL documentation](https://docs.silverstripe.org/en/4/developer_guides/graphql/), 
-provide [feedback](https://github.com/silverstripe/silverstripe-graphql/issues) and help us stabilise the module.
 
+We are planning to require the use of `silverstripe/graphql:^4` in a future CMS 4.x release.
+
+#### Start using Silverstripe GraphQL v4 today
+
+We encourage everyone to get started working with GraphQL v4 today:
+- You can start by reading our new [GraphQL documentation](https://docs.silverstripe.org/en/4/developer_guides/graphql/).
+- You can provide [feedback](https://github.com/silverstripe/silverstripe-graphql/issues) and help us stabilise the module.
+
+If your project uses `silverstripe/recipe-cms`, it is still locked to `silverstripe/graphql:^3.5`.
+To use `silverstripe/graphql:^4`, you'll need to "inline" the `silverstripe/recipe-cms` requirements
+in your root `composer.json` and change `silverstripe/graphql` to `^4`.
+
+You can inline `silverstripe/recipe-cms` by running this command:
+```bash
+composer update-recipe silverstripe/recipe-cms
+```
+
+Alternatively, you can remove `silverstripe/recipe-cms` from your root `composer.json` and replace
+it with the the contents of the `composer.json` in `silverstripe/recipe-cms`.
+
+
+#### GraphQL 3 code moved to _legacy folder
+
+You will notice that many of the core modules now have a `_legacy` directory in their root.
 In order to facilitate the new module release, most GraphQL helper classes to drive the CMS UI
 have been marked as deprecated, and moved to `GraphQL/_legacy` folders within core modules.
+This is a temporary fix that we have applied to satisfy the competing interests of semver and
+PSR-4 autoloading.
+
 The GraphQL schema under `admin/graphql` has been altered slightly to enable forwards compatibility,
 with lower-camelcase field names, and a different filter argument structure.
 In the unlikely case that you are relying on those classes or queries directly,
 consider upgrading to `silverstripe/graphql:^4`.
+
 Your own GraphQL schemas outside of `admin/graphql` should not be affected by the changes
 if you choose to stay on `silverstripe/graphql:^3` for the time being.
 
-We are planning to require the use of `silverstripe/graphql:^4` in a future CMS 4.x release.
-
-If your project uses `silverstripe/recipe-cms`, please note that it is still locked to use `silverstripe/graphql:^3`.  If you'd like to now use `silverstripe/graphql:^4` then you'll need remove `silverstripe/recipe-cms` from your root composer.json, and instead copy the contents of the composer.json in silverstripe/recipe-cms to your root composer.json and change `silverstripe/graphql` to `^4`.
-
-### GraphQL 3 code moved to _legacy folder {#graphql-v3-legacy}
-
-You will notice that many of the core modules now have a `_legacy` directory in their root.
-This is a temporary fix that we have applied to satisfy the competing interests of semver and
-PSR-4 autoloading.
-
-Because the semver contract precludes changing the fully-qualified names of any classes,
-we need to keep GraphQL 3 code untouched. But GraphQL 4 code often contains classes of similar
-or identical names, e.g. "ReadFilesResolver", or something to that effect. Further, this 
-backward compatibility creates a common demand for the canonical namespace "GraphQL.", e.g.
-`SilverStripe\AssetAdmin\GraphQL`. It didn't seem appropriate to put _old_ code in the "GraphQL"
-space, and _new_ code in a less obvious place, like `SilverStripe\AssetAdmin\GraphQL4`.
-
-A simple fix would have been to stuff all the GraphQL 3 code into `code/GraphQL/_legacy` and use `classmap` to shim the PSR-4 autoloader, but this is [no longer supported](https://blog.packagist.com/composer-2-0-is-now-available/#3-backwards-compatibility-breaks) in Composer 2.0.
-
-Thus, we ended up with the "least bad" solution, which was to create a parallel path resolution
-for GraphQL 3 code in the `_legacy` folder, alongside `code/` / `src/`.
-
 It is likely that in the future, we will mandate the use of GraphQL 4 in Silverstripe CMS, and
-remove this shim. We expect this happen within just one minor release, making `_legacy/` a very short-lived workaround.
+remove this shim. We expect this will happen within just one minor release, making `_legacy/` a very
+short-lived workaround.
 
 ### Improvements to the login form template and signed in period {#default-period}