Skip to content

Commit

Permalink
Merge pull request silverstripe#9964 from creative-commoners/pulls/4.…
Browse files Browse the repository at this point in the history 
…8/graphql-changelog-tweaks

DOC Tweak GraphQL changelog
  • Loading branch information
@emteknetnz
emteknetnz authored Jun 8, 2021
2 parents e950494 + 1fc1e71 commit d64c907
Showing 1 changed file with 45 additions and 36 deletions.
81 changes: 45 additions & 36 deletions docs/en/04_Changelogs/4.8.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`, 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.
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.

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.
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.
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 resulting`silverstripe/graphql:^4` release is currently in an alpha stage.

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`.
#### 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 {#graphql-v3-legacy}
#### 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.

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.
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`.

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/`.
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.

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}

Expand All @@ -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}

Expand All @@ -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


Expand Down Expand Up @@ -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


Expand Down Expand Up @@ -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


Expand All @@ -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


Expand All @@ -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


Expand Down Expand Up @@ -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


Expand Down Expand Up @@ -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 -->

0 comments on commit d64c907

Please sign in to comment.