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}
 
@@ -105,7 +114,7 @@ This change has been made to more accurately reflect what action will be taken,
 
 ### Other new features {#other-features}
 
-* [Added a `chunkedFetch()` method to `DataList`](/Developer_Guides/Model/Lists#chunkedFetch) to avoid loading large result sets in memory all at once. 
+* [Added a `chunkedFetch()` method to `DataList`](/Developer_Guides/Model/Lists#chunkedFetch) to avoid loading large result sets in memory all at once.
 
 ## Bugfixes {#bugfixes}
 
@@ -124,7 +133,7 @@ This release includes a number of bug fixes to improve a broad range of areas. C
  * silverstripe/graphql (3.4.1 -> 3.5.0)
     * 2021-02-09 [149b4ed](https://github.com/silverstripe/silverstripe-graphql/commit/149b4ed074a7e46750287c22e08c91d421abe1cc) Disable basic-auth for graphql requests (Steve Boyd) - See [cve-2020-26136](https://www.silverstripe.org/download/security-releases/cve-2020-26136)
 
-    
+
 ### Features and Enhancements
 
 
@@ -166,7 +175,7 @@ This release includes a number of bug fixes to improve a broad range of areas. C
     * 2021-04-14 [5ebdbff](https://github.com/silverstripe/silverstripe-login-forms/commit/5ebdbff9e4d57ccca04a6e230e9bf62d54515e7a) Use popover for help icon (Steve Boyd)
     * 2021-01-21 [1449aac](https://github.com/silverstripe/silverstripe-login-forms/commit/1449aac66db602b032dca50c90b6d04cd6aff3e2) Updating Silverstripe logo to new logo (#75) (3Dgoo)
 
-    
+
 ### Bugfixes
 
 
@@ -227,7 +236,7 @@ This release includes a number of bug fixes to improve a broad range of areas. C
     * 2021-02-15 [c618b63](https://github.com/silverstripe/silverstripe-login-forms/commit/c618b63529730fb989f4d04179b222745129f54f) Avoid clipping of the Silverstripe CMS logo (Maxime Rainville)
     * 2021-01-21 [1ac3429](https://github.com/silverstripe/silverstripe-login-forms/commit/1ac342993dc40a48ecfd8b566efa18eea9372573) Allow title and form to resize independently (#81) (Garion Herman)
 
-    
+
 ### API Changes
 
 
@@ -246,7 +255,7 @@ This release includes a number of bug fixes to improve a broad range of areas. C
  * silverstripe/graphql (3.4.1 -> 3.5.0)
     * 2021-05-10 [f8ac3f7](https://github.com/silverstripe/silverstripe-graphql/commit/f8ac3f757b055a8ec8327fddf77db3dee1afae62) Block older version module from using this minor (#379) (Maxime Rainville)
 
-    
+
 ### Dependencies
 
 
@@ -272,7 +281,7 @@ This release includes a number of bug fixes to improve a broad range of areas. C
     * 2020-12-11 [9e097f4](https://github.com/silverstripe/silverstripe-login-forms/commit/9e097f45c815b606a6936a6cb23b47cd206231f1) Bump ini from 1.3.5 to 1.3.7 (dependabot[bot])
     * 2020-11-12 [c06130e](https://github.com/silverstripe/silverstripe-login-forms/commit/c06130e613fcf02c8a64fee37dc323c1766ec1b9) Bump dot-prop from 4.2.0 to 4.2.1 (dependabot[bot])
 
-    
+
 ### Documentation
 
 
@@ -318,7 +327,7 @@ This release includes a number of bug fixes to improve a broad range of areas. C
     * 2020-11-03 [bf6a52b9c](https://github.com/silverstripe/silverstripe-framework/commit/bf6a52b9c0d8d73fe0dc3db9105761fe76f63f6f) Add some extra details to the changelog about toast notification and DataObject hydration (#9754) (Maxime Rainville)
     * 2020-10-15 [fee31c2c6](https://github.com/silverstripe/silverstripe-framework/commit/fee31c2c6cf09b8108d546340b663dd5101fd4b5) Recommend moving .protected out of webroot (Ingo Schommer)
 
-    
+
 ### Other changes
 
 
@@ -458,4 +467,4 @@ This release includes a number of bug fixes to improve a broad range of areas. C
     * 2021-01-21 [f38beb9](https://github.com/silverstripe/silverstripe-login-forms/commit/f38beb964af88a277bec05f5a57da39c726e4541) Update build status badge (Steve Boyd)
     * 2020-11-06 [127532c](https://github.com/silverstripe/silverstripe-login-forms/commit/127532cdf67e21d6ff6ba492717dc849f55add4c) Setting form max width (Michael Nowina-Krowicki)
 
-    <!--- Changes above this line will be automatically regenerated -->
+    <!--- Changes above this line will be automatically regenerated -->