deprecate use(Lazy)Query on(Error|Completed) callbacks

[phryneas]

Once we settled on a wording of the "deprecation issue", I'll open an issue and add the link to that in the deprecation messages and the changeset.

I'll be very happy for any feedback on wording or arguments.

[changeset-bot]

🦋 Changeset detected

Latest commit: 5bea158

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

This PR includes changesets to release 1 package

Name	Type
@apollo/client	Minor

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

[svc-apollo-docs]

⚠️ Docs preview not attached to branch

The preview was not built because the PR's base branch release-3.13 is not in the list of sources.

An Apollo team member can comment one of the following commands to dictate which branch to attach the preview to:

• !docs set-base-branch version-2.6
• !docs set-base-branch main

Build ID: 57f142b9f2b2a4ee7d844e14

[pkg-pr-new]

npm i https://pkg.pr.new/@apollo/client@12340

commit: 5bea158

[netlify]

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	5bea158
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/67a63797a0b05e0008ec595c
😎 Deploy Preview	https://deploy-preview-12340--apollo-client-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	41.24 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	50.68 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	47.75 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	36.24 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	33.63 KB (0%)
import { ApolloProvider } from "dist/react/index.js"	1.26 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.24 KB (0%)
import { useQuery } from "dist/react/index.js"	5.21 KB (0%)
import { useQuery } from "dist/react/index.js" (production)	4.29 KB (0%)
import { useLazyQuery } from "dist/react/index.js"	5.7 KB (0%)
import { useLazyQuery } from "dist/react/index.js" (production)	4.78 KB (0%)
import { useMutation } from "dist/react/index.js"	3.62 KB (0%)
import { useMutation } from "dist/react/index.js" (production)	2.84 KB (0%)
import { useSubscription } from "dist/react/index.js"	4.42 KB (0%)
import { useSubscription } from "dist/react/index.js" (production)	3.48 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js"	5.88 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.54 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js"	5.37 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js" (production)	4.03 KB (0%)
import { useLoadableQuery } from "dist/react/index.js"	5.45 KB (0%)
import { useLoadableQuery } from "dist/react/index.js" (production)	4.11 KB (0%)
import { useReadQuery } from "dist/react/index.js"	3.42 KB (0%)
import { useReadQuery } from "dist/react/index.js" (production)	3.36 KB (0%)
import { useFragment } from "dist/react/index.js"	2.36 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	2.31 KB (0%)

[jerelmiller]

I'll give this another read-through in the morning, but here is some initial feedback. Hope this helps.

[jerelmiller]

I think it might be good to add one more section on "bad practices". You do mention that we don't recommend the use of onCompleted right before this, but I think it would be good to go into a bit more detail on some specifics for why that is (e.g. cache can't be synced, etc.)

That, or perhaps state this early on in this document as one of the primary motivators behind this change so that much of this document can support that claim.

Basically I just want to make sure readers walk away with a solid understanding on why we don't recommend its use to begin with. Whether that is provided through its own section, or done as a statement in the beginning with the rest of this as supporting evidence would be great either way.

[phryneas]

Hmm, you clearly have a better idea what to write there than I do - could you maybe contribute that paragraph? 😅

[jerelmiller]

@Meschreiber would you perhaps be willing to take a look at this as well? We are deprecating some callbacks and want to provide some justification for doing so. Your feedback is always appreciated, especially since you're much better at English than I am, so your suggestions would probably make more sense than mine 😆

[jerelmiller]

@phryneas made a couple other tweaks and added a section on "our recommendation". Feel free to tweak or revert any of my updates as you see fit, but otherwise looks great on my end 🎉