Skip to content

docs: add first guide for schema governance series - #2267

Merged
martinbonnin merged 9 commits into
graphql:sourcefrom
sarahxsanders:schema-review
Jul 17, 2026
Merged

docs: add first guide for schema governance series#2267
martinbonnin merged 9 commits into
graphql:sourcefrom
sarahxsanders:schema-review

Conversation

@sarahxsanders

Copy link
Copy Markdown
Contributor

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

vercel Bot commented Dec 14, 2025

Copy link
Copy Markdown

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

@benjie
benjie marked this pull request as draft December 18, 2025 16:00
@martinbonnin

Copy link
Copy Markdown
Contributor

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

@sarahxsanders
sarahxsanders marked this pull request as ready for review February 17, 2026 22:33
@sarahxsanders

Copy link
Copy Markdown
Contributor Author

@martinbonnin yes this is ready!

@martinbonnin

Copy link
Copy Markdown
Contributor

Awesome @sarahxsanders ! I'll review now!

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

@Urigo Urigo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/pages/learn/_meta.ts Outdated
Comment thread src/pages/learn/schema-review.mdx Outdated
@vercel

vercel Bot commented Feb 26, 2026

Copy link
Copy Markdown

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

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

Request Review

@benjie

benjie commented Feb 26, 2026

Copy link
Copy Markdown
Member

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

Comment thread src/pages/learn/schema-review.mdx
Comment thread src/pages/learn/schema-review.mdx Outdated
sarahxsanders and others added 2 commits July 16, 2026 18:45
The added "schema-governance" member pushed the `section` union in cards.tsx
past the print width; wrap it so `prettier --check` (the failing CI job) passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment thread src/pages/learn/schema-review.mdx Outdated
Comment thread src/pages/learn/schema-review.mdx Outdated
Comment thread src/pages/learn/schema-review.mdx
Comment thread src/pages/learn/schema-review.mdx Outdated
Co-authored-by: Martin Bonnin <martin@mbonnin.net>
@martinbonnin
martinbonnin enabled auto-merge (squash) July 17, 2026 10:34
@martinbonnin
martinbonnin merged commit 0883ada into graphql:source Jul 17, 2026
4 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants