docs: describe query default changes in v5 (#8488)

Fixes #8485

Author: matt-tingen

docs/framework/react/guides/migrating-to-v5.md

@@ -420,6 +420,33 @@ This last change is technically a breaking one, and was made so we don't prematu
 + </HydrationBoundary> // [!code ++]
 ```
 
+### Query defaults changes
+
+`queryClient.getQueryDefaults` will now merge together all matching registrations instead of returning only the first matching registration.
+
+As a result, calls to `queryClient.setQueryDefaults` should now be ordered with _increasing_ specificity.
+That is, registrations should be made from the **most generic key** to the **least generic one**.
+
+For example:
+
+```ts
++ queryClient.setQueryDefaults(['todo'], {   // [!code ++]
++   retry: false,  // [!code ++]
++   staleTime: 60_000,  // [!code ++]
++ })  // [!code ++]
+queryClient.setQueryDefaults(['todo', 'detail'], {
++   retry: true,  // [!code --]
+  retryDelay: 1_000,
+  staleTime: 10_000,
+})
+- queryClient.setQueryDefaults(['todo'], { // [!code --]
+-   retry: false, // [!code --]
+-   staleTime: 60_000, // [!code --]
+- }) // [!code --]
+```
+
+Note that in this specific example, `retry: true` was added to the `['todo', 'detail']` registration to counteract it now inheriting `retry: false` from the more general registration. The specific changes needed to maintain exact behavior will vary depending on your defaults.
+
 [//]: # 'FrameworkSpecificBreakingChanges'
 
 ## New Features 🚀

docs/reference/QueryClient.md

@@ -522,8 +522,8 @@ The `getQueryDefaults` method returns the default options which have been set fo
 const defaultOptions = queryClient.getQueryDefaults(['posts'])
 ```
 
-> Note that if several query defaults match the given query key, the **first** matching one is returned.
-> This could lead to unexpected behaviours. See [`setQueryDefaults`](#queryclientsetquerydefaults).
+> Note that if several query defaults match the given query key, they will be merged together based on the order of registration.
+> See [`setQueryDefaults`](#queryclientsetquerydefaults).
 
 ## `queryClient.setQueryDefaults`
 
@@ -543,7 +543,8 @@ function Component() {
 - `options: QueryOptions`
 
 > As stated in [`getQueryDefaults`](#queryclientgetquerydefaults), the order of registration of query defaults does matter.
-> Since the **first** matching defaults are returned by `getQueryDefaults`, the registration should be made in the following order: from the **least generic key** to the **most generic one**. This way, in case of specific key, the first matching one would be the expected one.
+> Since the matching defaults are merged by `getQueryDefaults`, the registration should be made in the following order: from the **most generic key** to the **least generic one** .
+> This way, more specific defaults will override more generic defaults.
 
 ## `queryClient.getMutationDefaults`