docs: schema governance tooling#2319
Conversation
|
@sarahxsanders is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
|
@sarahxsanders were you looking into feedback already or should we wait a bit until this PR is not a draft? |
|
this one is ready too! @martinbonnin |
martinbonnin
left a comment
martinbonnin
left a comment
There was a problem hiding this comment.
A few comments. Nothing blocking. Thanks for looking into this ❤️
| run: npm ci | ||
|
|
||
| - name: Validate schema syntax | ||
| run: npx graphql-inspector validate ./schema/*.graphql |
There was a problem hiding this comment.
Are we OK mentioning vendor tools on graphql.org? (same for @apollo/composition a few lines below)
There was a problem hiding this comment.
my personal thought is that is ok and if another vendor complains/offers another solution, we add them as well
My thought process behind this is to give the user as much information as possible to make them successful, while doing it in the open to give all vendors a fair shot at solving the problem
|
|
||
| ### Alert on deprecated field usage | ||
|
|
||
| When clients continue using deprecated fields as the removal deadline approaches, send notifications to the responsible teams. |
There was a problem hiding this comment.
I'm curious how much that works in practice. The change is notified through the schema using @deprecated already. Adding another layer of automatic notification feels like duplication of effort.
I get that nudging colleagues is sometimes necessary but if it's an automatic email/notification and the client dev already ignored the @deprecated, there's a very high change they will ignore the notification similarly.
There was a problem hiding this comment.
fair!! updated slightly to clarify the value of these alerts is usage data, not the deprecation itself. i still think the usage data is important (which clients hit the field, how many requests, etc.)
lmk what you think
| run: npm ci | ||
|
|
||
| - name: Validate schema syntax | ||
| run: npx graphql-inspector validate ./schema/*.graphql |
There was a problem hiding this comment.
my personal thought is that is ok and if another vendor complains/offers another solution, we add them as well
My thought process behind this is to give the user as much information as possible to make them successful, while doing it in the open to give all vendors a fair shot at solving the problem
|
|
||
| Without usage data, deprecation timelines become guesswork. You either wait too long by maintaining deprecated fields indefinitely or move too fast by breaking clients who haven't migrated. Usage tracking lets you make informed decisions. | ||
|
|
||
| Most GraphQL servers support plugins that hook into query execution. The key data points to capture are: |
There was a problem hiding this comment.
In this section I would also link to https://graphql.org/resources/monitoring/ and probably give that section a bit of love
|
@martinbonnin addressed the feedback here!! |
5 participants
Description
adds a new governance tooling and automation page to the Learn section under a new "Schema Governance" category: