docs: add first guide for schema governance series

[sarahxsanders]

Description

adds the first guide for the new "schema governance" guides for graphql.org/learn

includes new guide: review and validate schema changes:

• defining review criteria
• automate validation
• CI/CD integration
• ownership and approval process
• breaking changes
• scaling
• pitfalls

Note

PLEASE DO NOT MERGE, THIS IS THE FIRST IN A THREE GUIDE SERIES

next guides are on:

• naming conventions and design standards: define consistent naming and documentation patterns
• schema ownership and governance: expand on the basics from this guide
• evolve schemas with versioning and tooling

[vercel]

@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.

[martinbonnin]

@sarahxsanders is this ready? Do you need feedbacks on this?

[sarahxsanders]

@martinbonnin yes this is ready!

[martinbonnin]

Awesome @sarahxsanders ! I'll review now!

@benjie @hasparus Do you have access to Vercel to approve the preview?

[Urigo]

great work, I won't comment here but some of the comments I've made in the other PR but in high level some of them are related here as well

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
graphql-github-io	Error		Apr 23, 2026 9:48am

[benjie]

Vercel is reporting the same issue as CI, which I believe was addressed in the comments above.

info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/basic-features/eslint#disabling-rules
Failed to compile.
./src/components/learn-aggregator/learn-pages.tsx:13:7
Type error: Property '"review-and-validate-schema-changes"' is missing in type '{ introduction: { description: string; icon: string; section: "getting-started"; }; schema: { description: string; icon: string; section: "getting-started"; }; queries: { description: string; icon: string; section: "getting-started"; }; ... 18 more ...; "debug-errors": { ...; }; }' but required in type 'Record<LearnPagePath, Omit<LearnPageItem, "title" | "href"> | null>'.
  11 | }
  12 |
> 13 | const _items: Record<
     |       ^
  14 |   LearnPagePath,
  15 |   Omit<LearnPageItem, "title" | "href"> | null
  16 | > = {
Next.js build worker exited with code: 1 and signal: null
 ELIFECYCLE  Command failed with exit code 1.
Error: Command "pnpm run build" exited with 1

[martinbonnin]

I would very much like that we change the narrative from "this is dangerous by default" to "this should be safe unless your frontend doesn't support it".

Suggested change

	Dangerous changes that may break some clients include:
	- **Adding enum values**: If clients exhaustively match enum values
	- **Adding fields to input types**: If clients use spread operators to construct input objects
	Some changes may break applications that did not plan for schema evolution:
	- **Adding enum values**: If application code exhaustively match enum values
	- **Adding new types to an union or interface**: If application code exhaustively match the type name
	- **Adding fields to input types**: If application code use spread operators to construct input objects
	Such applications make schema evolution harder and writing robust applications is encouraged.
	If in doubt, use caution when doing those changes.

I wrote a "Robust Applications" best practice PR there that we could then link from here.

[martinbonnin]

I'm not sure I understand this one. Did you have an example?