Skip to content

last pins, redis/salesforce/convex fixes, gemini, vertex and github graphql sources - #240

Open
adssib wants to merge 9 commits into
mainfrom
pl5-all
Open

adssib wants to merge 9 commits into
mainfrom
pl5-all

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Needs a minor release after merge. Exported API changed:

  • New: catalog.Commands, catalog.UpcomingChanges, versions.PyPIReleasesWithYanked, versions.FirstOfMajor, retire.Format, retire.Gemini, retire.Vertex.
  • Removed or changed: catalog.Catalog and catalog.Plugin; members.NumPy2, PostHog8 and NewRelic11 (now NumPy, PostHog, NewRelic, with no Release or DocsRef); migrationguide.Guide's GuideURL and Read; sdkguide.FirstOfMajor and AnthropicV1; changelog.Textual0860 and Urllib3200.

Closes #179
Closes #222
Closes #223
Closes #224

The combined branch of the stack, where CI and the review run. Each part has its own PR, with the details and the issue's checklist:

PR What
#233 #179: no release named in plugin code. NumPy, PostHog and New Relic guides read at every major (PyPI); test pins move to _test.go; TestNoPinnedReleaseInPluginCode
#234 #222: redis/commands reads src/commands/ at every Redis release tag (redis/redis), not the archived redis-doc
#235 #223: a living page that can't be read fails the run, never "nothing changed"; Salesforce's CDN 503 falls back to the archive like 401/403
#236 #224: Convex's get-convex → convex org
#237 new google/gemini-models (notices; Markdoc tables)
#238 new google/vertex-model-retirements (notices; HTML tables)
#239 new github/graphql (catalog; GitHub's GraphQL upcoming-changes file, commit by commit)

Sources added

id kind layer URL
google/gemini-models notices ai-models https://ai.google.dev/gemini-api/docs/deprecations (read at https://aistudio.google.com/docs/deprecations)
google/vertex-model-retirements notices ai-models https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions
github/graphql catalog api https://github.com/github/docs/blob/main/src/graphql/data/fpt/upcoming-changes.json

Every URL was re-checked on 2026-11-21 before it was written. Each source has its metadata in the registration (I read the words), a golden, a drop test, testdata/README.md rows and a provider page with Why this source.

High and medium notices/catalog candidates from the audit that aren't built, and why

None of these is waiting on a new kind. Each needs a contract subject, a different reader input, or has no source precise enough to emit valid events:

candidate priority why not
openai/deprecations (endpoint table) high The rows name a path (/v1/prompts, /v1/audio/translations) but no method, and the contract's operation is METHOD /path. Guessing the method isn't reading the page. Needs a path-wide operation in the contract.
anthropic/api-notices high Feature and beta-header deprecations (fast mode, beta headers): no contract subject for a feature or a header.
mongodb/server, neon/postgres-versions, redis/software-lifecycle, elastic/eol high / medium A server or runtime version's end of life: no contract subject. elastic/eol is also JS-rendered (unverified).
newrelic/eol (RSS) high Agent, integration and product EOLs; only one notice names REST operations, and those it names as "REST API v2" without operations. No subject fits the rest.
vercel/runtimes high The deprecation dates are only in an auto-generated "related pages" link block. A hosting runtime isn't the contract's ci_runtime (a CI platform).
supabase/changelog (RSS) high "Breaking Change" items in prose, with no typed subject to cite (precision over recall).
gitlab/rest-deprecations high Prose. The removals are tied to a v5 REST API GitLab says isn't being developed, with no date.
gitlab/deprecations (catalog) high YAML entries are feature deprecations by title and prose, not typed operations. Also needs a GitLab-hosted reader.
github/runner-images (issues) high Fits ci_runtime, but needs a reader for an issues list. That list changes on every comment (counts, timestamps), so a living-page read would snapshot it every run and the citation check would fail on churn. Needs a reader that hashes only the announcements. Meanwhile github/actions (the changelog feed) covers runner image retirements.
cloudflare/workers-compat-flags (catalog) medium A compatibility flag's default date: no contract subject. Also needs a Cap'n Proto annotation reader.
openai/changelog, google/gemini-changelog, github/changelog, cloudflare/changelog, vercel/changelog, neon/changelog medium Prose feeds that overlap a structured source already watched (openai/models, google/gemini-models, github/actions, cloudflare/api).
google/vertex-deprecations medium SDK module removals on a date: a package change needs a version pair, which a living page doesn't give.
github/rest-versions medium Prose per REST API version. github/api (the OpenAPI diff) covers those versions.
gitlab/deprecations-page, gitlab/graphql, gitlab/breaking-windows medium Prose, or windows of dates with no subject. gitlab/graphql's removed items could map like github/graphql; left for a follow-up.
elastic/elasticsearch-deprecations medium Prose per version.
supabase/breaking-changes medium GitHub Discussions (a GraphQL API reader), the same items as the changelog.

Calls I made (please check)

Checks

  • make check passes on every branch of the stack (go1.27.1).
  • Goldens: unchanged except convex.json (source_url org only, convex: read from the convex org #236) and the new ones (redis-commands, google-gemini-models, google-vertex-model-retirements, github-graphql).

Related PRs

🤖 Generated with Claude Code

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude encountered an error after 1m 35s —— View job


⚠️ Merge after fixes: the build, tests and rules all pass, but github/graphql can emit a duplicate deprecation when a commit removes still-upcoming entries and a later one restores them. Please fix that, or accept it in writing, before this ships.

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) ✅ google/gemini-models and google/vertex-model-retirements are in plugins/notices/notices.go. github/graphql and the new redis/commands are in plugins/catalog/catalog.go. NumPy, PostHog and New Relic Watches/URLs are rewritten in migrationguide.go. Each has an id, layer, watches, URLs, packages and a page. No hand-kept list came back.
Provider pages ✅ providers/github-graphql.md, google-gemini-models.md and google-vertex-model-retirements.md are new, each with a link, check date, why, alternatives and quote. redis.md, numpy.md, posthog.md, newrelic.md, salesforce.md and convex.md are updated.
Golden test + dated quote ✅ New goldens: redis-commands, github-graphql, google-gemini-models, google-vertex-model-retirements. Every new fixture has a testdata/README.md row with URL, date, license and quote. The convex.json golden changes only in source_url (the org), as the PR explains.
Drop test ✅ Redis 8.8.0 → 8.10.0 (nothing removed); GraphQL's past-dated re-adds from 2026-01-05..08; the Gemini 4 models and agents tables; the Vertex image-models table (minimum-lifetime dates).
Fetch only via env ✅ Every new reader uses env.Get or a core/versions / core/github helper; redis.go imports core/fetch only for StatusError. TestNoPinnedReleaseInPluginCode is a useful new guard.
Nothing private (Rule 2) ✅ / ℹ️ The leak guard is clean and the commit messages are clean. The PR body ends with "Handbook: developer-handbook#HB". If that's a private repo, please remove it from the public description.

Bugs

  • plugins/catalog/graphql.go:141, duplicate deprecations on a re-add. The reader compares each commit only with the one before it. Suppose a commit drops entries that are still upcoming (a bad regeneration or a revert) and the next commit restores them. Each restored entry is emitted again with a new version, so it gets a new fingerprint, and a client could open a second PR. The e.Date < to.Version.ID filter only catches past-dated re-adds. Details are in the inline comment. I'd fix this, or at least pin it with a drop test, before the source runs a backfill over its 29 commits.

Verified

  • go build ./...: ok
  • go vet ./...: no output
  • gofmt -l .: no output
  • go test -race ./...: every package ok, including plugins/all (TestNoPinnedReleaseInPluginCode), catalog, notices, notices/retire and migrationguide/members
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • Not run: make todos, make imports, make nethttp and go run ./cmd/list-plugins. They needed an approval I didn't have in this run. The registry tests passed, though.

Non-blocking

  • GraphQL subject mapping (inline at graphql.go:186): a removed root field (Query.x) becomes a request_parameter, and a non-root field's argument becomes a response-side schema_property. The fact in each event is right, but the kind or side may mislead a client.
  • Redis file rename: a command file renamed between releases with the same command inside reads as a removal. redis.md already lists this as a gap. A cheap guard: before emitting, check that the removed command's name isn't in any file added in to's listing. That needs only the added files, which is usually zero.
  • Salesforce 503 → archive: with this change, a real CDN outage also falls back to Wayback, though only after fetch's own retries. That's reasonable given 2026-11-21's behaviour; just a note that a 503 now no longer tells you the site was down.
  • retire.Parse: picking the first column that matches ^(shutdown|retirement) date$ and rejecting model == repl handles Vertex's "Model ID" / "Replacement model ID" correctly. Rows whose dates don't parse ("or later", footnote marks) are skipped. Both good for precision.
  • Thanks for the "high and medium candidates not built" table. It makes the scope easy to check.

var made []event.Event
var details []string
for _, e := range after {
if had[e.key()] || e.Date < to.Version.ID || e.Criticality != "breaking" {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Precision, worth a look (not blocking): this only compares against the previous commit. If a commit drops entries that are still upcoming (a bad regeneration or a reverted PR) and the next commit puts them back, every restored entry passes e.Date >= to.Version.ID and gets a second deprecation event. The fingerprint differs because Version is the new commit's date, so nothing downstream deduplicates it. The 2026-01-05..08 case is handled only because those entries were already past-dated.

One option: also skip an entry whose location@date was in the file in any earlier version this run has seen. Another: emit only when the location (at any date) is new, and treat a moved date as the gap the provider page already lists. A drop test that removes and restores a future-dated entry would pin either fix.

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.

Mapping (non-blocking, you flagged it): two locations land in an odd place here.

  • A root field itself (Query.someField, Mutation.someMutation, with no argument) becomes a request_parameter of POST /graphql with property Query.someField. It's a whole operation going away, not a parameter.
  • A non-root field's argument (Repository.issues.filterBy) goes to the schema_property branch with Property: "issues.filterBy", Side: response. An argument is sent, not received.

Neither emits a wrong fact, since the property string is still the exact location. But a client that matches on kind/side may look in the wrong place. Consider documenting both cases on the provider page, or splitting on the number of dots.

…t announced twice

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
@adssib

adssib commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

@claude review

Round 2. Fixed: github/graphql now uses the removal date as version, so an entry that is dropped and then restored gets the same fingerprint and is stored once (pinned by TestGraphQLARestoredEntryIsTheSameEvent). A root field (Query.x) is now a schema_property; only a root field's argument is a request_parameter. Removed the private handbook link from the descriptions. Left as is, as you noted: Redis file renames (a documented gap) and Salesforce 503 (by design).

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude encountered an error after 0s —— View job


I'll analyze this and get back to you.

@adssib

adssib commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

@claude review

Round 3 (the round-2 run failed inside the Action before reviewing). Since round 1: github/graphql uses the removal date as version, so a restored entry is deduped (TestGraphQLARestoredEntryIsTheSameEvent); a root field is a schema_property; the private handbook link is gone from the descriptions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant