First draft for upgrade guide to v17

website/pages/_meta.ts

@@ -20,6 +20,11 @@ const meta = {
   'oneof-input-objects': 'OneOf input objects',
   'defer-stream': '',
   '-- 3': {
+    type: 'separator',
+    title: 'Upgrade guides',
+  },
+  'v16-v17': '',
+  '-- 4': {
     type: 'separator',
     title: 'FAQ',
   },

website/pages/v16-v17.mdx

@@ -0,0 +1,129 @@
+---
+title: Upgrading from v16 to v17
+sidebarTitle: v16 to v17
+---
+
+import { Tabs } from 'nextra/components';
+
+# Breaking changes
+
+## Default values
+
+Previously default-values were assumed to be coerced internal values, now
+we will treat them like a pre-coerced external input value. This equalises
+how we treat default-values in SDL and variables over JSON.
+
+This goes hand-in-hand with the deprecation of `astFromValue` in favor of `valueToLiteral`.
+
+## GraphQLError constructor arguments
+
+The `GraphQLError` constructor now only accepts a message and options object as arguments. Previously, it also accepted positional arguments.
+
+```diff
+- new GraphQLError('message', 'source', 'positions', 'path', 'originalError', 'extensions');
++ new GraphQLError('message', { source, positions, path, originalError, extensions });
+```
+
+## `createSourceEventStream` arguments
+
+The `createSourceEventStream` function now only accepts an object as an argument. Previously, it also accepted positional arguments.
+
+```diff
+- createSourceEventStream(schema, document, rootValue, contextValue, variableValues, operationName);
++ createSourceEventStream({ schema, document, rootValue, contextValue, variableValues, operationName });
+```
+
+## `execute` will error for incremental delivery
+
+The `execute` function will now throw an error if it sees a `@defer` or `@stream` directive. Use `experimentalExecuteIncrementally` instead.
+If you know you are dealing with incremental delivery requests, you can replace the import.
+
+```diff
+- import { execute } from 'graphql';
++ import { experimentalExecuteIncrementally as execute } from 'graphql';
+```
+
+## Remove incremental delivery support from `subscribe`
+
+In case you have fragments that you use with `defer/stream` that end up in a subscription,
+use the `if` argument of the directive to disable it in your subscription operation
+
+## `subscribe` return type
+
+The `subscribe` function can now also return a non-Promise value, previously this was only a Promise.
+This shouldn't change a lot as `await value` will still work as expected. This could lead to
+some typing inconsistencies though.
+
+## Remove `singleResult` from incremental results
+
+You can remove branches that check for `singleResult` in your code, as it is no longer used.
+
+## Node support
+
+Dropped support for Node 14 (subject to change)
+
+## Removed `TokenKindEnum`, `KindEnum` and `DirectiveLocationEnum` types
+
+We have removed the `TokenKindEnum`, `KindEnum` and `DirectiveLocationEnum` types,
+use `Kind`, `TokenKind` and `DirectiveLocation` instead. https://github.com/graphql/graphql-js/pull/3579
+
+## Removed `graphql/subscription` module
+
+use `graphql/execution` instead for subscriptions, all execution related exports have been
+unified there.
+
+## Removed `GraphQLInterfaceTypeNormalizedConfig` export
+
+Use `ReturnType<GraphQLInterfaceType['toConfig']>` if you really need this
+
+## Empty AST collections will be undefined
+
+Empty AST collections will be presented by `undefined` rather than an empty array.
+
+## `Info.variableValues`
+
+The shape of `Info.variableValues` has changed to be an object containing
+`sources` and `coerced` as keys.
+
+A Source contains the `signature` and provided `value` pre-coercion for the
+variable. A `signature` is an object containing the `name`, `input-type` and
+`defaultValue` for the variable.
+
+## Removals
+
+- Removed exported `getOperationType` function
+- Removed exported `getVisitFn` function
+- Removed exported `printError` and `formatError` utilities
+- Removed exported `assertValidName` and `isValidNameError` utilities
+- Removed exported `assertValidExecutionArguments` function
+- Removed `getFieldDefFn` from `TypeInfo`
+- Removed `TypeInfo` from `validate` https://github.com/graphql/graphql-js/pull/4187
+
+## Deprecations
+
+- Deprecated  `astFromValue` use `valueToLiteral` instead, when leveraging `valueToLiteral` ensure
+  that you are working with externally provided values i.e. the SDL provided defaultValue to a variable.
+- Deprecated `valueFormAST` use `coerceInputLiteral` instead
+
+## New Features
+
+- Added `hideSuggestions` option to `execute`/`validate`/`subscribe`/... to hide schema-suggestions in error messages
+- Added `abortSignal` option to `graphql()`, `execute()`, and `subscribe()` allows cancellation of these methods;
+  the `abortSignal` can also be passed to field resolvers to cancel asynchronous work that they initiate.
+- `extensions` support `symbol` keys, in addition to the normal string keys.
+
+## New Experimental Features
+
+### Experimental Support for Incremental Delivery
+
+- [Spec PR](https://github.com/graphql/graphql-spec/pull/1110) / [RFC](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md)
+- enabled only when using `experimentalExecuteIncrementally()`, use of a schema or operation with `@defer`/`@stream` directives within `execute()` will now throw.
+- enable early execution with the new `enableEarlyExecution` configuration option for `experimentalExecuteIncrementally()`.
+
+### Experimental Support for Fragment Arguments
+
+- [Spec PR](https://github.com/graphql/graphql-spec/pull/1081)
+- enable with the new `experimentalFragmentArguments` configuration option for `parse()`.
+- new experimental `Kind.FRAGMENT_ARGUMENT` for visiting
+- new experimental `TypeInfo` methods and options for handling fragment arguments.
+- coerce AST via new function `coerceInputLiteral()` with experimental fragment variables argument (as opposed to deprecated `valueFromAST()` function).