introduce a versioning policy for Apollo Client #12850

phryneas · 2025-08-19T13:46:48Z

Out of the scope for this document, but a recommended read - this is how Ember defines SemVer in the context of TS types: https://rfcs.emberjs.com/id/0730-semver-for-ts/

changeset-bot · 2025-08-19T13:46:52Z

🦋 Changeset detected

Latest commit: 575cc23

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

phryneas · 2025-08-19T13:47:22Z

package.json

    "access": "public"
  },
  "files": [
-    "LICENSE",


see https://docs.npmjs.com/cli/v11/configuring-npm/package-json#files

pkg-pr-new · 2025-08-19T13:48:19Z

npm i https://pkg.pr.new/apollographql/apollo-client/@apollo/client@12850

commit: 575cc23

github-actions · 2025-08-19T13:48:59Z

size-limit report 📦

Path	Size
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (CJS)	42.89 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (production) (CJS)	37.72 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client"	32.83 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (production)	27.01 KB (0%)
import { ApolloProvider } from "@apollo/client/react"	5.91 KB (0%)
import { ApolloProvider } from "@apollo/client/react" (production)	970 B (0%)
import { useQuery } from "@apollo/client/react"	7.22 KB (0%)
import { useQuery } from "@apollo/client/react" (production)	2.23 KB (0%)
import { useLazyQuery } from "@apollo/client/react"	7.1 KB (0%)
import { useLazyQuery } from "@apollo/client/react" (production)	2.14 KB (0%)
import { useMutation } from "@apollo/client/react"	6.46 KB (0%)
import { useMutation } from "@apollo/client/react" (production)	1.48 KB (0%)
import { useSubscription } from "@apollo/client/react"	6.77 KB (0%)
import { useSubscription } from "@apollo/client/react" (production)	1.79 KB (0%)
import { useSuspenseQuery } from "@apollo/client/react"	8.58 KB (0%)
import { useSuspenseQuery } from "@apollo/client/react" (production)	3.62 KB (0%)
import { useBackgroundQuery } from "@apollo/client/react"	8.32 KB (0%)
import { useBackgroundQuery } from "@apollo/client/react" (production)	3.38 KB (0%)
import { useLoadableQuery } from "@apollo/client/react"	8.28 KB (0%)
import { useLoadableQuery } from "@apollo/client/react" (production)	3.36 KB (0%)
import { useReadQuery } from "@apollo/client/react"	6.58 KB (0%)
import { useReadQuery } from "@apollo/client/react" (production)	1.63 KB (0%)
import { useFragment } from "@apollo/client/react"	6.65 KB (0%)
import { useFragment } from "@apollo/client/react" (production)	1.71 KB (0%)

apollo-librarian · 2025-08-19T13:50:32Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

30 new, 64 changed, 7 removed

+ (developer-tools)/react/(latest)/api/link/apollo-link-base-batch-http.mdx
+ (developer-tools)/react/(latest)/api/link/apollo-link-base-http.mdx
+ (developer-tools)/react/(latest)/api/link/apollo-link-batch.mdx
+ (developer-tools)/react/(latest)/api/link/apollo-link-client-awareness.mdx
+ (developer-tools)/react/(latest)/api/link/apollo-link-persisted-queries.mdx
+ (developer-tools)/react/(latest)/api/link/apollo-link.mdx
+ (developer-tools)/react/(latest)/api/react/ApolloProvider.mdx
+ (developer-tools)/react/(latest)/api/react/skipToken.mdx
+ (developer-tools)/react/(latest)/api/react/useApolloClient.mdx
+ (developer-tools)/react/(latest)/api/react/useBackgroundQuery.mdx
+ (developer-tools)/react/(latest)/api/react/useFragment.mdx
+ (developer-tools)/react/(latest)/api/react/useLazyQuery.mdx
+ (developer-tools)/react/(latest)/api/react/useLoadableQuery.mdx
+ (developer-tools)/react/(latest)/api/react/useMutation.mdx
+ (developer-tools)/react/(latest)/api/react/useQuery.mdx
+ (developer-tools)/react/(latest)/api/react/useQueryRefHandlers.mdx
+ (developer-tools)/react/(latest)/api/react/useReactiveVar.mdx
+ (developer-tools)/react/(latest)/api/react/useReadQuery.mdx
+ (developer-tools)/react/(latest)/api/react/useSubscription.mdx
+ (developer-tools)/react/(latest)/api/react/useSuspenseQuery.mdx
+ (developer-tools)/react/(latest)/api/errors/CombinedGraphQLErrors.mdx
+ (developer-tools)/react/(latest)/api/errors/CombinedProtocolErrors.mdx
+ (developer-tools)/react/(latest)/api/errors/LinkError.mdx
+ (developer-tools)/react/(latest)/api/errors/LocalStateError.mdx
+ (developer-tools)/react/(latest)/api/errors/ServerError.mdx
+ (developer-tools)/react/(latest)/api/errors/ServerParseError.mdx
+ (developer-tools)/react/(latest)/api/errors/UnconventionalError.mdx
+ (developer-tools)/react/(latest)/data/persisted-queries.mdx
+ (developer-tools)/react/(latest)/data/typescript.mdx
+ (developer-tools)/react/(latest)/development-testing/graphql-codegen.mdx
* (developer-tools)/react/(latest)/get-started.mdx
* (developer-tools)/react/(latest)/index.mdx
* (developer-tools)/react/(latest)/why-apollo.mdx
* (developer-tools)/react/(latest)/api/cache/InMemoryCache.mdx
* (developer-tools)/react/(latest)/api/core/ApolloClient.mdx
* (developer-tools)/react/(latest)/api/core/ObservableQuery.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-batch-http.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-context.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-error.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-http.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-remove-typename.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-retry.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-schema.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-subscriptions.mdx
* (developer-tools)/react/(latest)/api/link/apollo-link-ws.mdx
* (developer-tools)/react/(latest)/api/link/community-links.mdx
* (developer-tools)/react/(latest)/api/link/introduction.mdx
* (developer-tools)/react/(latest)/api/react/hooks.mdx
* (developer-tools)/react/(latest)/api/react/preloading.mdx
* (developer-tools)/react/(latest)/api/react/ssr.mdx
* (developer-tools)/react/(latest)/api/react/testing.mdx
* (developer-tools)/react/(latest)/caching/advanced-topics.mdx
* (developer-tools)/react/(latest)/caching/cache-configuration.mdx
* (developer-tools)/react/(latest)/caching/cache-field-behavior.mdx
* (developer-tools)/react/(latest)/caching/cache-interaction.mdx
* (developer-tools)/react/(latest)/caching/garbage-collection.mdx
* (developer-tools)/react/(latest)/caching/memory-management.mdx
* (developer-tools)/react/(latest)/caching/overview.mdx
* (developer-tools)/react/(latest)/data/defer.mdx
* (developer-tools)/react/(latest)/data/directives.mdx
* (developer-tools)/react/(latest)/data/document-transforms.mdx
* (developer-tools)/react/(latest)/data/error-handling.mdx
* (developer-tools)/react/(latest)/data/file-uploads.mdx
* (developer-tools)/react/(latest)/data/fragments.mdx
* (developer-tools)/react/(latest)/data/mutations.mdx
* (developer-tools)/react/(latest)/data/operation-best-practices.mdx
* (developer-tools)/react/(latest)/data/queries.mdx
* (developer-tools)/react/(latest)/data/refetching.mdx
* (developer-tools)/react/(latest)/data/subscriptions.mdx
* (developer-tools)/react/(latest)/data/suspense.mdx
* (developer-tools)/react/(latest)/development-testing/client-schema-mocking.mdx
* (developer-tools)/react/(latest)/development-testing/developer-tooling.mdx
* (developer-tools)/react/(latest)/development-testing/schema-driven-testing.mdx
* (developer-tools)/react/(latest)/development-testing/testing.mdx
* (developer-tools)/react/(latest)/integrations/integrations.mdx
* (developer-tools)/react/(latest)/integrations/react-native.mdx
* (developer-tools)/react/(latest)/integrations/webpack.mdx
* (developer-tools)/react/(latest)/local-state/local-resolvers.mdx
* (developer-tools)/react/(latest)/local-state/local-state-management.mdx
* (developer-tools)/react/(latest)/local-state/managing-state-with-field-policies.mdx
* (developer-tools)/react/(latest)/local-state/reactive-variables.mdx
* (developer-tools)/react/(latest)/migrating/apollo-client-3-migration.mdx
* (developer-tools)/react/(latest)/networking/advanced-http-networking.mdx
* (developer-tools)/react/(latest)/networking/authentication.mdx
* (developer-tools)/react/(latest)/networking/basic-http-networking.mdx
* (developer-tools)/react/(latest)/pagination/core-api.mdx
* (developer-tools)/react/(latest)/pagination/cursor-based.mdx
* (developer-tools)/react/(latest)/pagination/key-args.mdx
* (developer-tools)/react/(latest)/pagination/offset-based.mdx
* (developer-tools)/react/(latest)/performance/babel.mdx
* (developer-tools)/react/(latest)/performance/optimistic-ui.mdx
* (developer-tools)/react/(latest)/performance/performance.mdx
* (developer-tools)/react/(latest)/performance/server-side-rendering.mdx
* (developer-tools)/react/(latest)/_sidebar.yaml
- (developer-tools)/react/(latest)/api/link/apollo-link-rest.mdx
- (developer-tools)/react/(latest)/api/link/persisted-queries.mdx
- (developer-tools)/react/(latest)/api/react/components.mdx
- (developer-tools)/react/(latest)/api/react/hoc.mdx
- (developer-tools)/react/(latest)/development-testing/static-typing.mdx
- (developer-tools)/react/(latest)/local-state/client-side-schema.mdx
- (developer-tools)/react/(latest)/migrating/hooks-migration.mdx

Build ID: 9b7c37a39ab8202710e2b281
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/9b7c37a39ab8202710e2b281

phryneas · 2025-08-19T13:58:26Z

VERSIONING.md

+- [`FinalizationRegistry`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) (already used by dependencies)
+- [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+
+## Dependencies


Should we also add a section about TypeScript types here, noting that sometimes changes to types that are perceived as "breaking" are necessary, and we might consider them, and that we can uphold semver only for runtime code, not for TS types?

Yes I would. Perhaps something like:

We reserve the right to update TypeScript types as needed, such as to fix bugs or add compatibility with various TypeScript features. Updates to types might requires changes to your application, but we do not consider these breaking changes.

Feel free to workshop that 🙂

added a section :)

jerelmiller

Had a few suggestions, but great overall! Really awesome to get this out there 🙂

VERSIONING.md

jerelmiller · 2025-08-19T17:06:42Z

VERSIONING.md

+
+### other dependencies
+
+We reserve the right to update dependencies in minor releases of Apollo Client, as well as dropping support for older versions of dependencies.


Should we add a statement specifically about peer dependencies in general? Perhaps maybe that should be its own section? Its unclear whether "dependencies" in this context refer to peer deps or just regular deps.

In other words, do we guarantee that we won't require new peer dependencies in a major release cycle, or do we want the freedom to be able to add peer dependencies?

This probably deserves its own title right above this section with a statement about it.

Moving that under "Other", since it will reference rules above it.

Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

phryneas · 2025-08-20T15:42:01Z

VERSIONING.md

@@ -0,0 +1,93 @@
+# Apollo Client Versioning Policy


rename to VERSIONING_POLICY.md

phryneas added 2 commits August 19, 2025 15:45

introduce a versioning policy for Apollo Client

2c4fe60

changeset

cc8fabd

phryneas commented Aug 19, 2025

View reviewed changes

phryneas requested a review from jerelmiller August 19, 2025 14:55

jerelmiller reviewed Aug 19, 2025

View reviewed changes

phryneas and others added 3 commits August 20, 2025 15:06

Apply suggestions from code review

5bb02d2

Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

add TS note

cecd694

peer dependency section

1693af7

phryneas requested a review from jerelmiller August 20, 2025 13:41

phryneas commented Aug 20, 2025

View reviewed changes

VERSIONING.md

@@ -0,0 +1,93 @@

# Apollo Client Versioning Policy

Copy link

Member Author

phryneas Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rename to VERSIONING_POLICY.md

phryneas added 2 commits August 20, 2025 18:46

rename VERSIONING.md to VERSIONING_POLICY.md

c8ede6f

add to sidebar

5283e48

phryneas requested a review from a team as a code owner August 20, 2025 16:51

phryneas added 2 commits August 20, 2025 18:54

move changelog down

1eca8c8

Merge branch 'release-4.0' into pr/versioning-policy

575cc23

phryneas merged commit 268cd80 into release-4.0 Aug 20, 2025
13 of 25 checks passed

github-actions bot mentioned this pull request Aug 20, 2025

Version Packages (rc) #12849

Merged

phryneas deleted the pr/versioning-policy branch August 20, 2025 17:18

jerelmiller mentioned this pull request Aug 20, 2025

[4.0] Provide new support matrix for external dependencies #12193

Closed

github-actions bot locked as resolved and limited conversation to collaborators Sep 20, 2025


		### other dependencies

		We reserve the right to update dependencies in minor releases of Apollo Client, as well as dropping support for older versions of dependencies.

introduce a versioning policy for Apollo Client #12850

introduce a versioning policy for Apollo Client #12850

Uh oh!

Conversation

phryneas commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

phryneas Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

apollo-librarian bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

phryneas Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

phryneas Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

jerelmiller left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jerelmiller Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

phryneas Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

phryneas Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

phryneas commented Aug 19, 2025 •

edited

Loading

changeset-bot bot commented Aug 19, 2025 •

edited

Loading

pkg-pr-new bot commented Aug 19, 2025 •

edited

Loading

github-actions bot commented Aug 19, 2025 •

edited

Loading

apollo-librarian bot commented Aug 19, 2025 •

edited

Loading