Repository navigation
add github/graphql: announced GraphQL removals #239
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
adssib
wants to merge
4
commits into
pl5-vertex
Choose a base branch
from
pl5-graphql
base: pl5-vertex
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+2,429
−7
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
f82d040
add github/graphql: announced GraphQL removals, commit by commit
adssib 3533785
github/graphql: the golden is three consecutive pairs
adssib 587a34d
github/graphql: version is the removal date, so a restored entry isn'…
adssib 0459a27
github/graphql: check the test's reads; say what the version pair means
adssib File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,199 @@ | ||
| package catalog | ||
|
|
||
| import ( | ||
| "context" | ||
| "encoding/json" | ||
| "fmt" | ||
| "html" | ||
| "regexp" | ||
| "sort" | ||
| "strings" | ||
|
|
||
| "github.com/patch-it-dev/patch-it-plugins/core/event" | ||
| "github.com/patch-it-dev/patch-it-plugins/core/github" | ||
| "github.com/patch-it-dev/patch-it-plugins/core/plugin" | ||
| "github.com/patch-it-dev/patch-it-plugins/core/versions" | ||
| ) | ||
|
|
||
| // UpcomingChanges is a GraphQL API's file of announced removals, kept in a | ||
| // repo and read at each commit that changed it: GitHub's | ||
| // src/graphql/data/fpt/upcoming-changes.json in github/docs, which | ||
| // docs.github.com's "Breaking changes" page is built from. The file is an | ||
| // object keyed by removal date, each a list of {location, description, | ||
| // reason, date, criticality}: location is "Type.field" (or | ||
| // "Type.field.argument"), date the day it goes. | ||
| // | ||
| // A version is a commit (its date, its SHA). An entry in to's file that | ||
| // from's didn't have is a newly announced removal: a deprecation event on | ||
| // that location whose version is the removal date (GitHub's GraphQL API has | ||
| // no versions of its own, so the day it breaks is the one to gate on, as a | ||
| // model's shutdown date is), with previous_version the commit before. An | ||
| // entry a commit drops and a later one restores, with the same date, is then | ||
| // the same event again, which the store dedupes by fingerprint. An entry dated before the commit that | ||
| // adds it isn't an announcement (a revert putting back a removal already | ||
| // made: the file lost and regained 17 such entries on 2026-01-05 and 06), and | ||
| // an entry that leaves the file isn't read: it shipped, or was withdrawn, | ||
| // and the file doesn't say which. | ||
| type UpcomingChanges struct { | ||
| API string // the source id the events carry: "github/graphql" | ||
| Vendor string // for sentences: "GitHub" | ||
| Repo string // owner/name on GitHub | ||
| Path string // the file's path in the repo | ||
| // Endpoint is the GraphQL endpoint as an operation: every query and | ||
| // mutation is a POST to it ("POST /graphql"). | ||
| Endpoint string | ||
| } | ||
|
|
||
| // GitHubGraphQL is GitHub's GraphQL API's upcoming changes (checked | ||
| // 2026-11-21: 1,291 entries, every one "criticality": "breaking", 29 | ||
| // commits since 2023-05-01). | ||
| var GitHubGraphQL = UpcomingChanges{ | ||
| API: "github/graphql", Vendor: "GitHub", | ||
| Repo: "github/docs", Path: "src/graphql/data/fpt/upcoming-changes.json", | ||
| Endpoint: "POST /graphql", | ||
| } | ||
|
|
||
| func (u UpcomingChanges) Name() string { return u.API } | ||
|
|
||
| // FileURL is the file at a commit: its own provenance. | ||
| func (u UpcomingChanges) FileURL(sha string) string { | ||
| return fmt.Sprintf("%s/%s/%s/%s", github.Raw, u.Repo, sha, u.Path) | ||
| } | ||
|
|
||
| // ListVersions is every commit that changed the file, oldest first. | ||
| func (u UpcomingChanges) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { | ||
| return versions.GitHubCommits(ctx, env.Get, u.Repo, u.Path) | ||
| } | ||
|
|
||
| // ReadAt fetches the file at v's commit. | ||
| func (u UpcomingChanges) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { | ||
| url := u.FileURL(v.Ref) | ||
| body, err := env.Get(ctx, url) | ||
| if err != nil { | ||
| return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err) | ||
| } | ||
| return plugin.Snapshot{Version: v, Content: body, SourceURL: url}, nil | ||
| } | ||
|
|
||
| // upcoming is one entry of the file: the fields read, in the file's order, | ||
| // which is also how an event quotes it (the entry's "owner", a GitHub team | ||
| // or handle, is left out). | ||
| type upcoming struct { | ||
| Location string `json:"location"` | ||
| Description string `json:"description"` | ||
| Reason string `json:"reason"` | ||
| Date string `json:"date"` | ||
| Criticality string `json:"criticality"` | ||
| } | ||
|
|
||
| func (e upcoming) key() string { return e.Location + "@" + e.Date } | ||
|
|
||
| // entries reads the file: every entry, in the file's order of dates. | ||
| func entries(body []byte) ([]upcoming, error) { | ||
| var byDate map[string][]json.RawMessage | ||
| if err := json.Unmarshal(body, &byDate); err != nil { | ||
| return nil, err | ||
| } | ||
| dates := make([]string, 0, len(byDate)) | ||
| for d := range byDate { | ||
| dates = append(dates, d) | ||
| } | ||
| sort.Strings(dates) | ||
| var out []upcoming | ||
| for _, d := range dates { | ||
| for _, r := range byDate[d] { | ||
| var e upcoming | ||
| if err := json.Unmarshal(r, &e); err != nil { | ||
| return nil, err | ||
| } | ||
| out = append(out, e) | ||
| } | ||
| } | ||
| return out, nil | ||
| } | ||
|
|
||
| var gqlTag = regexp.MustCompile(`<[^>]+>`) | ||
|
|
||
| // gqlText is an entry's HTML as one plain sentence. | ||
| func gqlText(s string) string { | ||
| return strings.Join(strings.Fields(html.UnescapeString(gqlTag.ReplaceAllString(s, ""))), " ") | ||
| } | ||
|
|
||
| // Extract is a deprecation event per entry in to's file that from's didn't | ||
| // have, dated before to's commit or not at all excluded (see | ||
| // UpcomingChanges), with previous_version from's commit. A zero from has | ||
| // nothing to compare. | ||
| func (u UpcomingChanges) Extract(_ context.Context, env plugin.Env, from, to plugin.Snapshot) (plugin.Result, error) { | ||
| if from.IsZero() { | ||
| return plugin.Result{}, nil | ||
| } | ||
| before, err := entries(from.Content) | ||
| if err != nil { | ||
| return plugin.Result{}, fmt.Errorf("reading %s: %w", from.SourceURL, err) | ||
| } | ||
| after, err := entries(to.Content) | ||
| if err != nil { | ||
| return plugin.Result{}, fmt.Errorf("reading %s: %w", to.SourceURL, err) | ||
| } | ||
| had := map[string]bool{} | ||
| for _, e := range before { | ||
| had[e.key()] = true | ||
| } | ||
| var made []event.Event | ||
| var details []string | ||
| for _, e := range after { | ||
| if had[e.key()] || e.Date < to.Version.ID || e.Criticality != "breaking" { | ||
| continue | ||
| } | ||
| subject, ok := u.subject(e.Location) | ||
| if !ok { | ||
| continue | ||
| } | ||
| var quote strings.Builder | ||
| enc := json.NewEncoder("e) | ||
| enc.SetEscapeHTML(false) | ||
| if err := enc.Encode(e); err != nil { | ||
| return plugin.Result{}, err | ||
| } | ||
| hint := gqlText(e.Description) | ||
| if r := gqlText(e.Reason); r != "" && r != hint { | ||
| hint += " " + r | ||
| } | ||
| made = append(made, event.Event{ | ||
| API: u.API, Version: e.Date, PreviousVersion: from.Version.ID, | ||
| ChangeType: event.ChangeTypeDeprecation, | ||
| Subject: subject, | ||
| Description: fmt.Sprintf("%s's GraphQL API removes %s on %s: code that queries or sends it fails from that date.", | ||
| u.Vendor, e.Location, e.Date), | ||
| MigrationHint: hint, | ||
| SourceURL: to.SourceURL, | ||
| SourceExcerpt: excerpt(strings.TrimSpace(quote.String())), | ||
| Confidence: 1.0, | ||
| DetectedAt: env.Now().UTC(), | ||
| }) | ||
| details = append(details, "") | ||
| } | ||
| events, rejected := finish(u.API, made, details) | ||
| return plugin.Result{Events: events, Rejected: rejected}, nil | ||
| } | ||
|
|
||
| // subject places a location in the contract's api_operation: an input | ||
| // object's field, or an argument of a root field (Query.field.argument), is | ||
| // a request parameter of the endpoint; any other location (a field, a root | ||
| // field itself, a field's argument, an enum's value) is a property of its | ||
| // type, as a schema. | ||
| func (u UpcomingChanges) subject(location string) (event.Subject, bool) { | ||
| typ, rest, ok := strings.Cut(location, ".") | ||
| if !ok || typ == "" || rest == "" { | ||
| return event.Subject{}, false | ||
| } | ||
| root := typ == "Query" || typ == "Mutation" || typ == "Subscription" | ||
| if strings.HasSuffix(typ, "Input") || (root && strings.Contains(rest, ".")) { | ||
| return event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindRequestParameter, Side: event.SideRequest, | ||
| Operation: u.Endpoint, Property: location}, true | ||
| } | ||
| return event.Subject{Type: event.SubjectAPIOperation, Kind: event.KindSchemaProperty, Side: event.SideResponse, | ||
| Schema: typ, Property: rest}, true | ||
| } | ||
|
|
||
| var _ plugin.Versioned = UpcomingChanges{} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,145 @@ | ||
| package catalog | ||
|
|
||
| import ( | ||
| "context" | ||
| "fmt" | ||
| "strings" | ||
| "testing" | ||
|
|
||
| "github.com/patch-it-dev/patch-it-plugins/core/event" | ||
| "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" | ||
| "github.com/patch-it-dev/patch-it-plugins/core/plugin" | ||
| "github.com/patch-it-dev/patch-it-plugins/core/versions" | ||
| ) | ||
|
|
||
| // The commits of github/docs the saved files are at (testdata/README.md), | ||
| // oldest first, as GitHub's commit list names them. | ||
| var graphqlCommits = []plugin.Version{ | ||
| {ID: "2026-01-05", Ref: "fc26275f90e62249fabc0f287255b3e5e60cb6e8"}, | ||
| {ID: "2026-01-06", Ref: "54c26c43342f7818c4001af7eaf6a3295e3f822d"}, | ||
| {ID: "2026-01-08", Ref: "2706f417a6afec24c57482d62f70035ee35c10fb"}, | ||
| {ID: "2026-02-13", Ref: "fc7cedfe9c6b2c0a40fd213cd18c0afc774b67fc"}, | ||
| {ID: "2026-03-03", Ref: "3a14e541873e834edf32b43b71911fe80d109a70"}, | ||
| {ID: "2026-05-22", Ref: "a934f06d211bef668253e3826c118a4e559dc1ba"}, | ||
| {ID: "2026-06-23", Ref: "c5738e5815fff90d38f0166f7c9949bfb664e003"}, | ||
| } | ||
|
|
||
| func graphqlPages() kittest.Pages { | ||
| pages := kittest.Pages{} | ||
| for _, v := range graphqlCommits { | ||
| pages[GitHubGraphQL.FileURL(v.Ref)] = "testdata/github-graphql-upcoming-changes-" + v.Ref[:8] + ".json" | ||
| } | ||
| return pages | ||
| } | ||
|
|
||
| func graphqlPair(t *testing.T, from, to plugin.Version) []event.Event { | ||
| t.Helper() | ||
| return kittest.Versions(t, kittest.Env(t, graphqlPages()), GitHubGraphQL, from, to) | ||
| } | ||
|
|
||
| // The golden test: four consecutive commits, three pairs. 2026-03-03 adds | ||
| // CheckAnnotation.databaseId and Artifact.databaseId (removed on | ||
| // 2027-01-01, in the file's order), 2026-05-22 User.viewerRelevantRepositories | ||
| // and 2026-06-23 CopilotAgentTask.type (both 2026-10-01). Every entry the | ||
| // commits share is no event. | ||
| func TestGraphQLGolden(t *testing.T) { | ||
| var got []event.Event | ||
| var names []string | ||
| for _, pair := range versions.Pairs(graphqlCommits[3:]) { | ||
| for _, e := range graphqlPair(t, pair[0], pair[1]) { | ||
| got = append(got, e) | ||
| names = append(names, fmt.Sprintf("%s->%s %s.%s", e.PreviousVersion, pair[1].ID, e.Subject.Schema, e.Subject.Property)) | ||
| } | ||
| } | ||
| want := "2026-02-13->2026-03-03 CheckAnnotation.databaseId | 2026-02-13->2026-03-03 Artifact.databaseId | 2026-03-03->2026-05-22 User.viewerRelevantRepositories | 2026-05-22->2026-06-23 CopilotAgentTask.type" | ||
| if strings.Join(names, " | ") != want { | ||
| t.Errorf("got %s\nwant %s", strings.Join(names, " | "), want) | ||
| } | ||
| for _, e := range got { | ||
| if e.ChangeType != event.ChangeTypeDeprecation || e.Subject.Kind != event.KindSchemaProperty || !strings.Contains(e.SourceExcerpt, `"criticality":"breaking"`) || strings.Contains(e.SourceExcerpt, "owner") { | ||
| t.Errorf("%+v", e) | ||
| } | ||
| } | ||
| for i := range got { | ||
| got[i].ID = 0 | ||
| } | ||
| kittest.Golden(t, "testdata/golden/github-graphql.json", got) | ||
| } | ||
|
|
||
| // The pinned drop test: on 2026-01-05 the file lost 17 entries (removals | ||
| // dated 2024-07-01 to 2026-01-01, already made), got them back the next day | ||
| // and lost them again on 2026-01-08. Putting back a removal already past | ||
| // isn't an announcement, and an entry leaving the file says nothing: no | ||
| // event in either pair, though the second pair adds 17 entries. | ||
| func TestGraphQLRevertsAreNoAnnouncement(t *testing.T) { | ||
| for _, pair := range versions.Pairs(graphqlCommits[:3]) { | ||
| if got := graphqlPair(t, pair[0], pair[1]); len(got) != 0 { | ||
| t.Errorf("%s -> %s: %d events, want 0", pair[0].ID, pair[1].ID, len(got)) | ||
| } | ||
| } | ||
| // The second pair does add entries: what the date check drops. | ||
| from, _ := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[0]) | ||
| to, _ := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[1]) | ||
| a, _ := entries(from.Content) | ||
| b, _ := entries(to.Content) | ||
| if len(b)-len(a) != 17 { | ||
| t.Errorf("the re-added entries: %d, want 17", len(b)-len(a)) | ||
| } | ||
| } | ||
|
|
||
| // An input object's field and a root field's argument are request | ||
| // parameters of POST /graphql; any other location is a property of its type. | ||
| func TestGraphQLLocations(t *testing.T) { | ||
| for loc, want := range map[string]string{ | ||
| "AddPullRequestReviewInput.comments": "request_parameter POST /graphql AddPullRequestReviewInput.comments", | ||
| "Query.sponsorables.dependencyEcosystem": "request_parameter POST /graphql Query.sponsorables.dependencyEcosystem", | ||
| "RepositoryPermission.TRIAGE_PLUS": "schema_property RepositoryPermission TRIAGE_PLUS", | ||
| "Issue.stateReason.enableDuplicate": "schema_property Issue stateReason.enableDuplicate", | ||
| } { | ||
| s, ok := GitHubGraphQL.subject(loc) | ||
| got := strings.Join(strings.Fields(fmt.Sprintf("%s %s %s %s", s.Kind, s.Operation, s.Schema, s.Property)), " ") | ||
| if !ok || got != want { | ||
| t.Errorf("%s: %q, want %q", loc, got, want) | ||
| } | ||
| } | ||
| if _, ok := GitHubGraphQL.subject("NoDot"); ok { | ||
| t.Error("a location without a field isn't read") | ||
| } | ||
| } | ||
|
|
||
| func TestGraphQLVersionsAreTheFilesCommits(t *testing.T) { | ||
| env := kittest.Env(t, kittest.Pages{ | ||
| "https://api.github.com/repos/github/docs/commits?path=src%2Fgraphql%2Fdata%2Ffpt%2Fupcoming-changes.json&per_page=100&page=1": "testdata/github-commits-upcoming-changes-excerpt.json", | ||
| }) | ||
| vs, err := GitHubGraphQL.ListVersions(context.Background(), env) | ||
| if err != nil || len(vs) != 3 || vs[0].Ref != graphqlCommits[3].Ref || vs[2].ID != "2026-05-22" { | ||
| t.Errorf("%v %v", vs, err) | ||
| } | ||
| } | ||
|
|
||
| // An entry a commit drops while still upcoming and a later commit restores | ||
| // is the same event: its version is the removal date, not the commit's, so | ||
| // the fingerprint matches and the store keeps one. | ||
| func TestGraphQLARestoredEntryIsTheSameEvent(t *testing.T) { | ||
| first := graphqlPair(t, graphqlCommits[3], graphqlCommits[4]) | ||
| // 2026-03-03's file without its two additions, then the file again. | ||
| from, err := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[3]) | ||
| if err != nil { | ||
| t.Fatal(err) | ||
| } | ||
| to, err := GitHubGraphQL.ReadAt(context.Background(), kittest.Env(t, graphqlPages()), graphqlCommits[4]) | ||
| if err != nil { | ||
| t.Fatal(err) | ||
| } | ||
| from.Version = plugin.Version{ID: "2026-04-01", Ref: "dropped"} | ||
| to.Version = plugin.Version{ID: "2026-04-02", Ref: "restored"} | ||
| again, err := GitHubGraphQL.Extract(context.Background(), kittest.Env(t, nil), from, to) | ||
| if err != nil || len(again.Events) != len(first) { | ||
| t.Fatalf("%v, %d events", err, len(again.Events)) | ||
| } | ||
| for i, e := range again.Events { | ||
| if e.Version != "2027-01-01" || e.Fingerprint != first[i].Fingerprint { | ||
| t.Errorf("%s: version %s, same fingerprint %v", e.Subject.Property, e.Version, e.Fingerprint == first[i].Fingerprint) | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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 newversion, 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'sfromalready had (keyed onLocationalone), and add a line to the page about the "removed and put back while still in the future" case.