Skip to content

Commit 6df0929

Browse files
heiskrheiskr
authored
Expand README for src/graphql (#58895)
1 parent 050ec52 commit 6df0929

File tree

1 file changed

+142
-26
lines changed

1 file changed

+142
-26
lines changed

‎src/graphql/README.md‎

Lines changed: 142 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,155 @@
11
# GraphQL
22

3-
## About this directory
3+
The graphql subject handles GitHub's GraphQL API documentation, including schema synchronization, data generation, and documentation rendering. It fetches schema data from GitHub's GraphQL API and generates version-specific JSON files used to render the docs.
44

5-
* `src/graphql/lib` and `src/graphql/scripts` are human-editable.
6-
* `src/graphql/data/**` are generated by [scripts](./scripts).
5+
## Purpose & Scope
76

8-
## Editable files
7+
This subject is responsible for:
8+
- Syncing GraphQL schema from GitHub's API
9+
- Generating version-specific schema JSON files
10+
- Managing GraphQL previews, upcoming changes, and changelog
11+
- Middleware that injects GraphQL data into page context
12+
- Rendering GraphQL reference documentation
13+
- Validating GraphQL schema data structure
914

10-
* `src/graphql/lib/validator.json`
11-
- JSON schema used in `tests/graphql.ts`.
12-
* `src/graphql/lib/non-schema-scalars.json`
13-
- An array of scalar types that live in [`graphql-ruby`](https://github.com/rmosolgo/graphql-ruby/tree/356d9d369e444423bf06cab3dc767ec75fbc6745/lib/graphql/types) only. These are
14-
not part of the core GraphQL spec.
15-
* `src/graphql/lib/types.json`
16-
- High-level GraphQL types and kinds.
15+
## Architecture & Key Assets
1716

18-
## Data files
17+
### Key capabilities and their locations
1918

20-
Generated by `src/graphql/scripts/sync.ts`:
19+
- **Schema synchronization** - `scripts/sync.ts` fetches schema from GitHub's GraphQL API
20+
- **Data generation** - Generates version-specific JSON files in `data/VERSION/` directories (e.g., `data/ghec/schema.json`)
21+
- **Validation** - `lib/validator.ts` validates schema structure
22+
- **Data loading** - `lib/index.ts` provides functions to load GraphQL data in Next.js pages
23+
- **Content rendering** - Markdown files in `content/graphql/` use Liquid to render documentation
2124

22-
* `src/graphql/data/schema-VERSION.json` (separate files per version)
23-
* `src/graphql/data/previews.json`
24-
* `src/graphql/data/upcoming-changes.json`
25-
* `src/graphql/data/changelog.json`
25+
## Setup & Usage
2626

27-
## Rendering docs
27+
### Syncing GraphQL schema
2828

29-
When the server starts, `middleware/graphql.ts` accesses the static JSON files, fetches the data for the current version, and adds it to the `context` object. The added properties are:
29+
Run the sync script to fetch latest schema:
3030

31-
* `context.graphql.schemaForCurrentVersion`
32-
* `context.graphql.previewsForCurrentVersion`
33-
* `context.graphql.upcomingChangesForCurrentVersion`
34-
* `context.graphql.changelog`
31+
```bash
32+
npm run sync-graphql
33+
```
3534

36-
Markdown files in `content/graphql` use Liquid to loop over these context properties. The Liquid calls HTML files in the `includes` directory to do most of the rendering.
35+
This:
36+
1. Fetches schema from GitHub's GraphQL API for each version
37+
2. Generates `data/VERSION/schema.json` files (e.g., `data/ghec/schema.json`)
38+
3. Builds `data/previews.json`, `data/upcoming-changes.json`, `data/changelog.json`
39+
40+
### Running tests
41+
42+
```bash
43+
npm run test -- src/graphql/tests
44+
```
45+
46+
### How rendering works
47+
48+
1. GraphQL data is loaded directly in Next.js pages using `getServerSideProps`
49+
2. Functions from `lib/index.ts` like `getGraphqlSchema()` provide the data
50+
3. Data includes:
51+
- Schema for current version
52+
- Previews for current version
53+
- Upcoming changes for current version
54+
- Changelog
55+
4. Markdown files in `content/graphql/` use Liquid to loop over this data
56+
5. Liquid calls HTML includes in `includes/` for rendering
57+
58+
## Data & External Dependencies
59+
60+
### Data inputs
61+
- GitHub GraphQL API - Schema introspection queries
62+
- `lib/non-schema-scalars.json` - Custom scalar types from graphql-ruby
63+
- `lib/types.json` - High-level GraphQL types and kinds
64+
- `lib/validator.json` - JSON schema for validation
65+
66+
### Dependencies
67+
- GitHub GraphQL API access
68+
- `graphql-ruby` library scalars
69+
- JSON schema validator (AJV)
70+
- `@/versions` - Version mapping for schema files
71+
72+
### Data outputs
73+
- `data/schema-VERSION.json` - One file per version (ghec, ghes-3.11, etc.)
74+
- `data/previews.json` - Preview features across versions
75+
- `data/upcoming-changes.json` - Upcoming breaking changes
76+
- `data/changelog.json` - GraphQL API changelog entries
77+
78+
### Generated files
79+
80+
All files in `data/` are generated and should not be manually edited:
81+
- ✅ Edit: `lib/*.json`, `scripts/*.ts`
82+
- ❌ Don't edit: `data/*.json` (regenerate with sync script)
83+
84+
## Cross-links & Ownership
85+
86+
### Related subjects
87+
- [`src/rest`](../rest/README.md) - Similar pattern for REST API docs
88+
- [`src/webhooks`](../webhooks/README.md) - Similar pattern for webhooks docs
89+
- [`src/content-render`](../content-render/README.md) - Liquid rendering of GraphQL data
90+
- Content files in `content/graphql/` - GraphQL documentation pages
91+
92+
### Internal documentation
93+
- GitHub GraphQL API: https://docs.github.com/graphql
94+
- graphql-ruby scalars: https://github.com/rmosolgo/graphql-ruby
95+
96+
## Current State & Next Steps
97+
98+
### Editable files
99+
100+
Human-editable configuration:
101+
- `lib/validator.ts` - TypeScript file for validating schema in `tests/graphql.ts`
102+
- `lib/non-schema-scalars.json` - Scalar types from graphql-ruby (not in core spec)
103+
- `lib/types.json` - High-level GraphQL types and kinds
104+
105+
### Version-specific schemas
106+
107+
Schema files generated per version:
108+
- `data/ghec/schema.json` - GitHub Enterprise Cloud
109+
- `data/ghes-3.11/schema.json`, `data/ghes-3.10/schema.json`, etc. - GHES versions
110+
- Older versions may be archived
111+
112+
### Content authoring
113+
114+
Writers can add content to Markdown files in `content/graphql/` alongside Liquid:
115+
- Note that Markdown files exist for every URL in GraphQL docs
116+
- Liquid loops over `context.graphql.*` properties
117+
- Most rendering happens in `includes/` HTML files
118+
119+
### Known limitations
120+
- Schema sync requires API access
121+
- Generated files can be large (100KB+ per version)
122+
- Changes to upstream schema require re-sync
123+
- Validation schema must be kept in sync with expected structure
124+
125+
### Sync workflow
126+
127+
Automated sync (if configured):
128+
- Scheduled workflow checks for schema updates
129+
- Creates PR if changes detected
130+
- Manual sync: `npm run sync-graphql`
131+
132+
### Adding new schema versions
133+
134+
When a new GHES version releases:
135+
1. Update version list in sync script
136+
2. Run `npm run sync-graphql`
137+
3. Commit new `data/ghes-X.XX/schema.json` file
138+
4. Update content if needed
139+
140+
### Troubleshooting
141+
142+
**Sync fails:**
143+
- Check API access and authentication
144+
- Verify version mappings are correct
145+
- Check for schema validation errors
146+
147+
**Schema not loading:**
148+
- Verify `data/VERSION/schema.json` exists (e.g., `data/ghec/schema.json`)
149+
- Verify version detection logic
150+
151+
**Content not rendering:**
152+
- Check Liquid syntax in `content/graphql/`
153+
- Verify context properties are available
154+
- Check includes in `includes/` directory
37155

38-
Note that Markdown files exist in `content/graphql` for every URL available in our GraphQL
39-
documentation. Writers can add content to the Markdown files alongside the Liquid.

0 commit comments

Comments
 (0)