Skip to content

add github/graphql: announced GraphQL removals - #239

Open
adssib wants to merge 4 commits into
pl5-vertexfrom
pl5-graphql
Open

adssib wants to merge 4 commits into
pl5-vertexfrom
pl5-graphql

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #238

Part of #188 (I21.3, github/graphql)

What this changes

New source github/graphql (kind catalog, layer api). As the audit recommends over the HTML page I21.3 proposed, it reads src/graphql/data/fpt/upcoming-changes.json in github/docs, the file docs.github.com's GraphQL "Breaking changes" page is built from (re-checked 2026-11-21, 200), at every commit that changed it (29 since 2023-05).

  • An entry the newer commit adds is a deprecation event, its version the removal date (the API has no versions; like a model shutdown date), previous_version the commit before. An entry dropped while still upcoming and restored later is the same event (same fingerprint).
  • Subject (api_operation):
    • an input object's field, or a root field's argument, is a request_parameter of POST /graphql;
    • any other location, a root field itself included, is a schema_property (type → schema, field → property).
  • Not read: an entry dated before the commit that adds it (a revert of a removal already made: 17 such on 2026-01-05/06/08), and an entry that leaves the file (shipped or withdrawn: the file doesn't say which).
  • The excerpt is the entry's fields, its owner (a GitHub team or handle) left out.
  • Package: npm:@octokit/graphql.

Checklist

  • Metadata complete in the registration (I read the words)
  • Golden: four consecutive real commits, three pairs (excerpts of the real files, every kept entry unchanged)
  • testdata/README.md rows
  • Pinned drop test: the 2026-01-05 → 06 → 08 revert, 17 entries removed, put back and removed again, gives no event
  • providers/github-graphql.md
  • make check passes

Calls I made (please check)

  • GraphQL in the contract's api_operation. The contract has no GraphQL subject, so a GraphQL location is mapped as above. If the client should treat GraphQL differently, the contract needs a subject first.
  • The removal day isn't a separate breaking event. The deprecation names the date, and an entry leaving the file doesn't say it shipped.

Related PRs

🤖 Generated with Claude Code

adssib and others added 2 commits November 20, 2026 21:13
@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 29s —— View job


✅ Ready to merge: the metadata is complete, the golden and drop tests use real saved commits, it fetches only through env.Get, and everything I ran passed. I left two non-blocking notes inline.

Rules

Rule Status Evidence
Metadata in registration (Rule 1) ✅ plugins/catalog/catalog.go:32-41: id, name, category, homepage; source id graphql, layer api, Watches, URLs, Packages npm:@octokit/graphql, Page. registered_test.go covers it. No hand-kept list was added.
Provider page ✅ providers/github-graphql.md: Why this source has the link, the date checked (2026-11-21), why it's the best source, three alternatives and a quote.
Golden test + quote ✅ testdata/golden/github-graphql.json: 4 events over 3 consecutive real commit pairs. Every event carries a raw URL pinned to its commit SHA and the entry as its excerpt (owner left out). Each saved file has a row in testdata/README.md.
Pinned drop test ✅ TestGraphQLRevertsAreNoAnnouncement: the real 2026-01-05 → 06 → 08 revert, where 17 past-dated entries are re-added and then removed again, produces no event. The test also asserts the 17 additions really are there.
Fetch only via env ✅ ReadAt uses env.Get, and ListVersions uses versions.GitHubCommits(ctx, env.Get, …). There's no net/http, filesystem or DB access.
Contract fixtures untouched ✅ Nothing under contract/ changed.
Nothing private (Rule 2) ✅ The leak guard is clean. The code, testdata, PR body and commit messages contain no internal names, credentials or session links. The excerpt deliberately drops owner.
DCO ✅ Both commits are signed off and keep their co-author trailer.

Bugs

None found.

The change to finish (the new details parameter) is safe: Redis passes nil and gets the same fingerprints as before (its golden is unchanged and still passes). Filtering out entries dated before the commit fits the "precision over recall" rule well.

Verified

  • go build ./...: ok
  • go vet ./...: ok
  • gofmt -l .: printed nothing
  • go test -race ./...: all packages ok, including plugins/catalog
  • python3 scripts/leak_guard.py --all: no banned terms (8 hashed terms checked)
  • I couldn't run make check in this runner because the command needed approval, so make imports, make nethttp and make todos weren't run separately. A grep shows no TODO(new-plugin) and no net/http in the new files.

Non-blocking

  1. A postponed or re-added future entry reads as a new announcement (inline on graphql.go:85). Because the key includes the date, a moved date, or an entry that's removed and put back while still in the future, produces a second deprecation with a new fingerprint. The postponement case is already listed under Known gaps. You could key on Location alone to tighten it.
  2. A bare root field maps to request_parameter (inline on graphql.go:186). Query.foo (no argument) also matches, although the comment and the page say "root field's argument". You could adjust the wording or the check, and add a test row.
  3. License row: the README says CC BY 4.0. In github/docs, content/ and data/ are CC BY 4.0, but code under src/ is MIT. You may want to double-check which license covers src/graphql/data/ and say that in the README row.
  4. Same-day commits: GitHubCommits IDs a version by date, so two commits on one day that touch the file give a pair with version == previous_version. That comes from the existing core helper, not this PR, and is harmless here because subjects differ, but it's worth knowing.

Criticality string `json:"criticality"`
}

func (e upcoming) key() string { return e.Location + "@" + e.Date }

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-blocking (precision): because the key includes Date, an entry GitHub postpones (same location, new future date) reads as a fresh announcement. And an entry that's removed by mistake and put back while its date is still in the future gets announced a second time. In both cases the event gets a new version, so it also gets a new fingerprint, and downstream sees a second deprecation for a location it was already told about. The page lists the postponement under Known gaps, which is fine. If you want it tighter, you could skip a location that any earlier commit in the pair's from already had (keyed on Location alone), and add a line to the page about the "removed and put back while still in the future" case.

Comment thread plugins/catalog/graphql.go Outdated
if !ok || typ == "" || rest == "" {
return event.Subject{}, false
}
if strings.HasSuffix(typ, "Input") || typ == "Query" || typ == "Mutation" || typ == "Subscription" {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-blocking: the doc comment and the provider page both say "a root field's argument", but this branch also matches a root field itself (Query.foo, with no argument part). That becomes a request_parameter whose property is Query.foo, even though removing a root field is really removing an operation. Either the page could say so, or you could require a second dot for the Query/Mutation/Subscription case (strings.Contains(rest, ".")) and let a bare root field fall through to schema_property (Query / foo). It might be worth a row in TestGraphQLLocations either way.

adssib and others added 2 commits November 20, 2026 21:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant