Skip to content

Commit 60e0d35

Browse files
authored
docs: add product update for input based breaking changes (#6900)
1 parent be97f04 commit 60e0d35

File tree

1 file changed

+57
-0
lines changed
  • packages/web/docs/src/app/product-updates/(posts)/2025-05-20-advanced-breaking-changes

1 file changed

+57
-0
lines changed
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Input Based Breaking Change Detection
3+
description:
4+
Improvements to Hive's breaking change detection to make it easier and safer to migrate schemas.
5+
date: 2025-05-20
6+
authors: [jdolle]
7+
---
8+
9+
## What’s New?
10+
11+
- **Hive accounts for argument, input field, and variable values when checking for breaking
12+
changes** – This improvement is fully backwards compatible and will automatically take effect when
13+
upgrading your hive client package(s).
14+
15+
Compatible client versions include versions greater than or equal to:
16+
17+
- @graphql-hive/apollo@0.39.1
18+
- @graphql-hive/envelop@0.36.1
19+
- @graphql-hive/yoga@0.42.1
20+
21+
## Feature Details
22+
23+
Breaking change detection is complicated. It starts in the
24+
[graphql-hive client packages](https://the-guild.dev/graphql/hive/docs/api-reference/client), where
25+
operations are processed into a list of requested fields and types.
26+
27+
For example, an operation `{ user(id: "1234") { id } }` will produce this list of coordinates:
28+
29+
- Query
30+
- Query.user
31+
- Query.user.id
32+
- User
33+
- User.id
34+
- ID
35+
36+
These coordinates, along with other useful metrics like latency and error status, are sent to Hive's
37+
servers in batches from the client(s). Hive processes and stores this usage data by timestamp and
38+
coordinate. These are then aggregated over time to produce what's seen on Hive's explorer and
39+
insights pages, as well as to detect whether not a specific change to the schema will break clients.
40+
41+
This approach works well, but previously, it only collected from the type definitions used by the
42+
operation. But this release adds an additional coordinate for inputs with an indicator if the data
43+
is provided by clients, either as a value or variable.
44+
45+
For the above example, an additional coordinate is generated:
46+
47+
- Query.user.id!
48+
49+
The exclamation (!) indicates that this argument was passed a value. This helps distinguish whether
50+
or not an input field or argument can be converted from nullable to non-nullable safely.
51+
52+
We are excited about this feature because it provides greater accuracy and convenience for our
53+
users, while keeping their schemas safe.
54+
55+
---
56+
57+
[For more information about conditional breaking changes, see the Target Management docs](/docs/management/targets#conditional-breaking-changes).

0 commit comments

Comments
 (0)