From b6e4747b7489422ddaf949781b9ce8fecd66bc91 Mon Sep 17 00:00:00 2001 From: Aaron Carlino Date: Mon, 16 Nov 2020 11:09:56 +1300 Subject: [PATCH] DOCS: Add blurb about _legacy to changelog --- docs/en/04_Changelogs/4.8.0.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/en/04_Changelogs/4.8.0.md b/docs/en/04_Changelogs/4.8.0.md index 3b8d973ce..22e930765 100644 --- a/docs/en/04_Changelogs/4.8.0.md +++ b/docs/en/04_Changelogs/4.8.0.md @@ -28,3 +28,24 @@ Your own GraphQL schemas outside of `admin/graphql` should not be affected by th 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. + +#### GraphQL 3 code moved to _legacy folder + +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.