WIP edits to AS3 changelog #5286
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,34 +9,89 @@ The version headers in this history reflect the versions of Apollo Server itself | |
|
|
||
| ## v3.0.0 (PRERELEASE) | ||
|
|
||
| > The changes in this `v3.0.0` section have not been finalized. This section aims to track all changes that are going into the 3.0 release, but it is not comprehensive until the 3.0 release is finalized. | ||
|
|
||
| ### BREAKING CHANGES | ||
|
|
||
| #### Bumped dependencies | ||
|
|
||
| The minimum versions of these dependencies have been bumped to provide an improved foundation for the development of future features. | ||
|
|
||
| - Dropped support for Node.js v6, v8 and v10. Apollo Server 3.x is being compiled to ES2020, which maps to Node.js 12+. | ||
| - Note also that we only test Apollo Server on _even-numbered_ versions of Node.js, and we only aim to support Node.js versions that are under [long-term support](https://nodejs.org/en/about/releases/#releases) from the Node.js Foundation. | ||
| - Dropped support for versions of the `graphql` library prior to `15.3.0`. | ||
| - The `mocks` option of the `ApolloServer` constructor now uses `@graphql-tools/mock` v7 instead of `graphql-tools` v4, which causes some [breaking changes](https://www.graphql-tools.com/docs/mocking#migration-from-v7-and-below). | ||
| - For example, mock functions no longer receive arguments and cannot return `Promise`s. | ||
| - Note that some parts of the v7 migration guide suggest using the `resolvers` argument to `addMocksToSchema`. Apollo Server does not support this option, but you can call `addMocksToSchema` yourself and pass the result to the `schema` option of the `ApolloServer` constructor. | ||
|
|
||
| #### Removed functionality | ||
|
|
||
| Certain undersupported and underused Apollo Server features have been removed in favor of current or future methods for achieving similar functionality. Many of these features can be manually re-enabled, as listed below. | ||
|
|
||
| - Dropped built-in partial support for subscriptions via the `subscriptions-transport-ws` package. | ||
| - This integration did not support many Apollo Server features, and `subscriptions-transport-ws` has not been actively maintained. | ||
| - To re-enable subscriptions in Apollo Server 3 as they're supported in v2, [see the migration guide](./docs/source/migration.md#Subscriptions). | ||
| - We hope to provide more deeply integrated subscription support in a future release. | ||
| - Dropped built-in support for file uploads via the `graphql-upload` package. | ||
| - To re-enable file uploads in Apollo Server 3 as they're supported in v2, [see the migration guide](./docs/source/migration.md#File-uploads). | ||
| - Dropped support for the `graphql-extensions` API (e.g., `GraphQLExtensions`, `extensions`) in favor of the Apollo Server [plugins API](https://www.apollographql.com/docs/apollo-server/integrations/plugins/). | ||
| - Dropped support for passing the `schemaDirectives` option to the `ApolloServer` constructor. | ||
| - This option was passed directly to the `graphql-tools` function `makeExecutableSchema`. To continue using it, you can import `makeExecutableSchema` from `@graphql-tools/schema` and call it yourself: | ||
|
|
||
| ``` | ||
| new ApolloServer({ | ||
| schema: makeExecutableSchema({ | ||
| typeDefs, | ||
| resolvers, | ||
| schemaDirectives | ||
| }) | ||
| }) | ||
| ``` | ||
|
|
||
| Note that `graphql-tools` calls this feature ["legacy" schema directives](https://www.graphql-tools.com/docs/legacy-schema-directives/), and you might want to consider the newer [`schemaTransforms`](https://www.graphql-tools.com/docs/schema-directives/) option instead. | ||
| - Removed the deprecated `ApolloServer.schema` field, which never worked with federated gateways. | ||
| - To extract your schema from your server, you can make a plugin with `serverWillStart` or register `onSchemaChange` on your gateway. | ||
| - `apollo-datasource-rest`: We no longer officially support overriding the `baseURL` property with a getter, because TypeScript 4 does not allow you to do so. | ||
| - Removed the automatic addition of the `@cacheControl` directive to schemas. | ||
| - This directive was added in some circumstances but not in others, which led to confusion. | ||
| - If you use `@cacheControl`, you can [define it in your schema as shown in the docs](https://www.apollographql.com/docs/apollo-server/performance/caching/#in-your-schema-static). | ||
| - Removed the `tracing` option passed to the `ApolloServer` constructor. The corresponding `apollo-server-tracing` package has been deprecated and is no longer being published. | ||
| - This package implemented an inefficient JSON format for execution traces returned via the `tracing` GraphQL response extension. This format was only consumed by the deprecated `engineproxy` and GraphQL Playground. | ||
| - If you rely on this trace format, the old version of `apollo-server-tracing` should still work: | ||
|
|
||
| ``` | ||
| new ApolloServer({ | ||
| plugins: [ | ||
| require('apollo-server-tracing').plugin() | ||
| ] | ||
| }); | ||
| ``` | ||
| - Removed the `cacheControl` option passed to the `ApolloServer` constructor. The functionality provided by `cacheControl: true` or `cacheControl: {stripFormattedExtensions: false}` (which included a `cacheControl` extension in the GraphQL response, for use by the deprecated `engineproxy`) has been entirely removed. By default, Apollo Server continues to calculate an overall cache policy and to set the `Cache-Control` HTTP header, but this is now implemented directly inside `apollo-server-core` rather than a separate `apollo-cache-control` package (this package has been deprecated and is no longer being published). Tweaking cache control settings like `defaultMaxAge` is now done via the newly exported `ApolloServerPluginCacheControl` plugin rather than as a top-level constructor option. This follows the same pattern as the other built-in plugins like usage reporting. The `CacheHint` and `CacheScope` types are now exported from `apollo-server-types`. The `info.cacheControl.cacheHint` object now has additional methods `replace`, `restrict`, and `policyIfCacheable`, and its fields update when those methods or `setCacheHint` are called. These methods also exist on `requestContext.overallCachePolicy`, which is always defined and which should not be overwritten (use `replace` instead). There is also a new function `info.cacheControl.cacheHintFromType` available. `@cacheControl` directives on type extensions are no longer ignored. Fields returning union types are now treated similarly to fields returning object and interface types (`@cacheControl` directives on the type are honored, the default `maxAge` is applied to them). New feature: `@cacheControl(inheritMaxAge: true)` when applied to a composite type or a field returning a composite type means that the default `maxAge` is not applied to that field (unless it is a root field). | ||
|
|
||
| - Top-level exports have changed. For example: | ||
|
|
||
| - We no longer re-export the entirety of `graphql-tools` (including `makeExecutableSchema`) from all Apollo Server packages. To continue using them, install [`graphql-tools`](https://www.graphql-tools.com/) or one of its sub-packages yourself. | ||
| - The `Upload` scalar is no longer exported as part of dropping built-in support for file uploads. | ||
| - Support for serving an HTML UI has been generalized. While servers in dev mode still default to serving GraphQL Playground (note: this may change before v3.0.0), plugins can define a new `renderLandingPage` hook which returns an HTML page that is served to browsers. The `playground` option to `new ApolloServer` has been removed; customizing Playground or making it run in production mode can be done by installing the new `ApolloServerPluginLandingPageGraphQLPlayground` plugin yourself. To disable Playground, either install the new `ApolloServerPluginLandingPageDisabled` plugin or install any other plugin that implements `renderLandingPage`. Packages no longer export `defaultPlaygroundOptions`, `PlaygroundConfig`, and `PlaygroundRenderPageOptions`. By default, no GraphQL Playground settings are overridden, including the endpoint, which now just defaults to `window.location.href` (with most query parameters removed); this means you typically don't have to manually configure the endpoint. | ||
| - Stopped publishing the deprecated `apollo-server-testing` package. This package is just a wrapper around `server.executeOperation`, which you can use directly. | ||
| - `apollo-server-caching`: The test suite helper works differently, and the `TestableKeyValueCache` interface is removed. | ||
|
|
||
| #### Changes to Node.js framework integrations | ||
|
|
||
| - When using a non-serverless framework integration (Express, Fastify, Hapi, Koa, Micro, or Cloudflare), you now *must* call `await server.start()` before attaching the server to your framework. | ||
| * This method was introduced in v2.22 but was optional prior to Apollo Server 3. | ||
| * This does not apply to the core `apollo-server` library or to _serverless_ framework integrations. | ||
|
There was a problem hiding this comment. I don't think "core" is right here: this isn't about |
||
| - `apollo-server-express` no longer officially supports using with the `connect` framework. | ||
| - We have not actively removed any `connect` compatibility code, and we do still test that it works with `connect`. However, we reserve the right to break that compatibility without a major version bump of this package (we will certainly note in this changelog if we do so). | ||
| - `apollo-server-lambda`: This package is now implemented as a wrapper around `apollo-server-express`. `createHandler`'s argument now has different options: | ||
|
There was a problem hiding this comment. Another Lambda improvement is that we now have better support for running behind an ALB instead of just being API Gateway. (See #5291) |
||
| - `expressGetMiddlewareOptions`, which includes options like `cors` and is passed through to `apollo-server-express`'s `getMiddleware` | ||
| - `expressAppFromMiddleware`, which lets you customize HTTP processing | ||
|
|
||
| Also, the `context` function now receives an `express: { req, res }` option in addition to `event` and `context` | ||
| - `apollo-server-lambda`: The handler returned by `createHandler` can now only be called as an async function returning a `Promise` (it no longer optionally accepts a callback as the third argument). | ||
| - All current Lambda Node runtimes support this invocation mode (so `exports.handler = server.createHandler()` will keep working without any changes). | ||
| - If you've written your _own_ handler that calls the handler returned by `createHandler` with a callback, you'll need to handle its `Promise` return value instead. | ||
| - `apollo-server-fastify` is now compatible with Fastify v3 instead of Fastify v2. | ||
|
|
||
| ## vNEXT | ||
|
|
||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
interesting, you don't like the active voice here? (also below I'm noticing I have "is being compiled to ES2020" which probably has a better wording.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not so much active vs. passive as it is including "us" in the language, feels reasonable to keep it more neutrally perspectived, but this was far from a critical edit on my part 🤷♂️