Repository navigation
Conversation
One kind for a guide that lists what a release removed: the SDK guide and the removed-members readers implement migrationguide.Guide, and one Plugin lists, reads and extracts for both. plugins/removedmembers only forwards now; old kind names resolve through plugin.CanonicalKind. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
changelog.Plugin reads a Markdown/RST changelog (File) or a JSON one (Log). The JSON one now lists its versions (the commits that changed the file), reads each, and extracts what a commit added. plugins/apichangelog only forwards. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
One Plugin reads every live page of dated notices: fetch, unchanged check, shape guard and blocked-page fallback as reader options, Wayback cite, events, baseline. The deprecations-page, feed and end-of-life readers live under plugins/notices; the RSS/Atom and HTML helpers move to core/extract. The old packages only forward. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
GitHub, GitLab, Elasticsearch, Sentry, Algolia and Appwrite list every version of their spec, tested on recorded responses. versions.WaybackCaptures lists a living page's distinct Web Archive captures (CDX), and the notices kind reads and extracts them pair by pair, so a page's history can be backfilled by date. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Each source lists the packages it covers (ecosystem:name) and plugin.ForPackage finds a package's sources; the list prints them with each source's first name and aliases, for the contract switch to source ids. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Python first: every release on PyPI, its wheel (or sdist) read in memory as text by pysurface (no import, no execution, no new dependency), and consecutive surfaces compared into removed and renamed symbols, removed parameters and parameters that lost their default. Registers openai/python-sdk, with a golden over two trimmed real wheels. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
--provider/--name/--category/--homepage, --source/--kind/--reader/--layer, --url and --package (repeatable), asked for in a terminal when missing; every kind and reader scaffolds (apisurface included, an OpenAPI adapter gets its Versions stub), plugins/all gets a new kind's import, and the old --format flags keep working for one release. make new-plugin ARGS=. docs/which-kind.md asks which kind a source is; a test checks every registered source's kind is one of its answers. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
plugin/, event/, fetch/, migrate/, kit/ (and kit/kittest/), retire/ and sdkguide/ only forwarded to core/ and plugins/. Code importing them moves to core/plugin, core/event, core/fetch, core/migrate, core/kit, plugins/notices/retire and plugins/migrationguide/sdkguide. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
|
Claude finished @adssib's task in 1m 49s —— View job
Rules
Bugs (blocking, all precision in
|
| for _, g := range byParent { | ||
| if len(g[0]) == 1 && len(g[1]) == 1 { | ||
| old, now := a[g[0][0]], b[g[1][0]] | ||
| if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && len(old.Params) > 0 { |
There was a problem hiding this comment.
Precision: a rename can be inferred from self alone. len(old.Params) > 0 counts self, so for methods the only "same parameters" evidence can be [self]. Example: a class drops close(self) and, in the same release, adds an unrelated aclose(self) (or to_dict(self) → model_dump(self), which isn't a drop-in). That becomes a renamed_symbol with the hint "Use aclose, with the same parameters", which is a confident and wrong fix in someone's PR.
Suggestion: only count it as a rename when at least one parameter besides a leading self/cls matches. Otherwise fall back to removed_symbol, which is still true.
real := func(ps []pysurface.Param) int {
if len(ps) > 0 && (ps[0].Name == "self" || ps[0].Name == "cls") {
return len(ps) - 1
}
return len(ps)
}
if old.Params != nil && !old.Overloaded && !now.Overloaded && slices.Equal(old.Params, now.Params) && real(old.Params) > 0 {| now := env.Now().UTC() | ||
| var events []event.EventV2 | ||
| var rejected []error | ||
| for _, c := range Compare(a.Surface, b.Surface) { |
There was a problem hiding this comment.
Precision: a file that crosses MaxFileBytes makes every symbol in it look removed. If a module was read at the older release but skipped at the newer one because it grew past 4 MiB (b.Skipped), every class, function and method defined in it, plus every re-export of them, is missing from b.Surface. Each one then becomes a removed_symbol breaking event, even though nothing was removed. The doc comment in artifact.go says a skipped file is "a gap in the surface, never guessed at", but here the gap is read as a removal.
Suggestion: before building events, drop (and log) any change whose Before.File is in b.Skipped or a.Skipped. Or refuse the pair outright when the two skipped lists differ.
There was a problem hiding this comment.
Fixed in 00cf574: a removal whose definition's file is in the newer release's Skipped list is a logged note ("… was too big to read"), never an event; that covers its re-exports too, since a re-export carries its definition's file. Test: TestASkippedFileRemovesNothing.
| continue // its class is reported | ||
| } | ||
| before := a[k] | ||
| c := Change{Change: event.PackageRemovedSymbol, Kind: before.Kind, Symbol: k, Before: &before} |
There was a problem hiding this comment.
Precision: a method moved up to a base class is reported as removed. The provider page lists "Inherited methods aren't followed to the base class" as a known gap, but what it actually does is produce a false event, not miss one. If openai.X.create moves to a shared base class in the package (common in generated SDKs that get refactored), X.create drops out of the surface and this line emits removed_symbol, even though X().create(...) still works. The same thing happens when a def becomes a class attribute (create = _create) or a @property becomes a plain attribute.
A cheap guard: for a removed method whose class still exists, look at the class's base list (it's already in Signature). If it names a class the package defines, or it changed between the two releases, downgrade the change to a Note (logged, no event).
There was a problem hiding this comment.
Fixed in 00cf574, a bit more precisely than the suggestion: each release's snapshot now keeps the package's classes that are named as a base (private modules and names included) with their bases and every name their bodies define (pysurface.ReadClasses). A removed method whose class is still there is a note when (a) the class's bases changed, (b) the class itself now defines the name (create = _create, a property made a plain attribute), or (c) a base, followed through the package's own classes, defines it. A base outside the package with unchanged bases still reads as removed (documented as a known gap on the provider page). Test: TestAMethodMovedUpIsNotRemoved, plus TestReadClasses. The golden is unchanged.
…r a method moved up Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Signed-off-by: adssib <[email protected]>
Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
- core/event: the v1 ChangeEvent, its fingerprint and core/migrate are gone; every reader builds event.Event (was EventV2) directly. api_operation's kind type is event.Kind. - A source's plugin is named by its id, provider/source, and its events carry that id in api. The old slugs, Alias/Aliases/first_name, Register by slug and Lookup by slug are gone; RegisterProvider refuses a plugin whose Name isn't its source's id. plugins.json drops alias, first_name and aliases. - Replay, Replayer and Spec.Replay are gone: a version pair is ReadAt twice and Extract (kittest.Pair in tests). catalog gains ListVersions, ReadAt and Extract, so every kind is read version by version. - new-plugin: --format, --api and the old meanings of --provider and --source are gone; files are named <provider>-<source>. Goldens regenerated on purpose: api is now the source id, and since the fingerprint hashes api, every fingerprint changed with it. Checked with a script: old and new goldens are identical once api and fingerprint are set aside (three normalize goldens also move from v1's affected to subject). Two notices goldens are renamed to their id (cloudflare-api.json, google-vertex-ai-models.json). Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
|
@claude review This round (details in the updated PR body):
Local: |
|
Claude finished @adssib's task in 1m 5s —— View job
Rules
Blocking
Checked and fine
Non-blocking
|
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Signed-off-by: adssib <[email protected]>
Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
|
@claude review Fixes for the last review:
Local: |
|
Claude finished @adssib's task in 27s —— View job ✅ Ready to merge. The last blocker is fixed, and it's tested through the real reader. Only two small wording leftovers remain, and neither blocks.
Rules
The blocker, re-checked
Non-blocking
Thanks for working through three rounds so carefully. The |
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: adssib <[email protected]>
The one PR to merge for plugins part 2 (I19): branch
pl2-allis the top of the stack (#213 → #214 → #215 → #216 → #217 → #218 → #219 → #220). The stacked PRs are there to review one step at a time; merging this one lands them all (close them after).Closes #175 · Closes #176 · Closes #177 · Closes #178 · Closes #181 · Closes #182 · Part of #179 and #171
What it contains
removedmembers→ amigrationguidereader (members); onePlugin, oneExtractapichangelog→ thechangelogkind's JSON parser, now versioned by commitretirements+feed+eol→ onenoticeskind (shared steps once;ShapeGuard,ArchiveWhenBlocked); RSS/HTML helpers →core/extractversions.WaybackCaptures;noticesbackfilled by date from capturesSource.Packages(ecosystem:name),plugin.ForPackageapisurfacekind (Python, static, no new dependency),openai/python-sdk, golden over two trimmed real wheels; npm → #212new-pluginby provider/source/kind/reader with prompts, every kind incl.apisurface;make new-plugin;docs/which-kind.mdCanonicalKinddeleted; one event type (v1 andcore/migratedeleted); sources named only by theirprovider/sourceid, which events carry inapi(old slugs, aliases,first_namedeleted);Replay/Replayerdeleted,catalogread version by version;new-plugin's--format/--apideleted. Plus the fixes from the first review ofapisurface(#218)Six kinds after this:
openapi,changelog,notices,migrationguide,catalog,apisurface. Top level:core/ plugins/ cmd/ internal/ docs/ providers/ contract/ scripts/ .github(internal/pluginlistbuilds the list forcmd/list-plugins).Golden proof
Up to #219 every existing golden is a byte-identical rename. In #220, every golden is regenerated on purpose, in one commit (
one event type, sources named by their id, …):apiis now the source id (stripe→stripe/api,openai-models→openai/models, …), and the fingerprint hashesapi, so every fingerprint changes with it. A script compared each old golden with its new one withapiandfingerprintset aside: all 23 are otherwise identical (the threecore/normalizegoldens also move from v1'saffectedtosubject, same fields). Two notices goldens are renamed to their id:cloudflare-api.json,google-vertex-ai-models.json.make checkpasses (go1.27.1, incl. gofmt), andscripts/check_contract.pyagainst patch-itmain'sfixtures/passes (the copy is unchanged; it's resynced after patch-it#58 merges).What the next bump changes for the hosted ingestion service
Forwarders deleted; ingest must switch imports on its v0.4.0 bump. Ingest pins v0.3.0, where every old path still exists, so nothing breaks until it bumps. Old → new:
plugins/retirements(retirements.Plugin)plugins/notices(notices.Plugin{Page: retire.OpenAI})plugins/retirements/retireplugins/notices/retireplugins/feedplugins/notices+plugins/notices/feedplugins/eolplugins/notices+plugins/notices/eolplugins/removedmembersplugins/migrationguide+plugins/migrationguide/membersplugins/apichangelogplugins/changelog(changelog.Plugin{Log: …})core/migrate(migrate.ToV2,Fresh)event.EventV2,DecodeV2,FingerprintV2event.Event,Decode,Fingerprintevent.ChangeEvent,event.Affected,event.AffectedKind*event.Kind*for an api_operation subject's kindplugin.Register, lookup by old slugRegisterProvideronly;Lookup/LookupSource/Namestake and returnprovider/sourceidsSourceInfo.Alias(),Aliases();alias,first_name,aliasesin plugins.jsonplugin.Replayer,Spec.Replay,plugin.Baseline(…, replay, now),kittest.Replayplugin.Baseline(…, now);kittest.Pairreads and extracts a version pairplugins/notices/…,plugins/migrationguide/…,plugins/changelog/…; goldensplugins/notices/testdata/golden/<provider>-<source>.jsonEvents'
apiis theprovider/sourceid after the bump, so every fingerprint differs from what v0.3.0 stored: with no data to keep, the database is reset, not migrated. The every-golden check gainsplugins/apisurface/testdata/golden/openai-1.1.2.json(a version pair:ReadAtboth,Extract).What still uses
Run/Env.Baselines/plugin.Spec, and why it isn't deleted here: every kind now implementsListVersions/ReadAt/Extract, butnotices' living-page read (fetch the page now, compare with the last baseline's hash, cite a fresh Wayback snapshot) exists only asRun, and the ingest worker's living-page path calls it. DeletingRunmeans giving that read its own method and changing ingest's worker in the same step, and converting the 17 test files whose goldens run throughkittest.Ingest(Runtwice) to version pairs. That's its own change (worker + plugins together), not a cleanup; on the versioned kindsRunis otherwise only used by those tests.Releasing
The Release workflow's scheduled run skips when a new
plugins/<kind>/directory appears (notices,apisurface): the first release after this merges is a minor, run by hand (agents never release).Calls I made (please check)
feedmerged intonotices(as asked for this rewrite; I19.6 · One notices kind #177 said feed stays separate).apiis theprovider/sourceid now, ahead of patch-it#58 merging: no one consumes these events yet, and the contract change says ids only.new-pluginadds one source per run; its files are named<provider>-<source>(no--api, no--format).apisurfacereview fixes (on add the apisurface kind: a Python package's public API between releases (I19.10) #218): a rename needs a matching parameter besidesself/cls; a symbol in a file the newer release couldn't read (overMaxFileBytes) is a logged note, not a removal; a removed method whose class still exists is a note when the class's bases changed, a base class in the package (private ones included) now defines it, or the class now defines the name as an attribute. To follow bases, each release's snapshot keeps the package's base classes and the names their bodies define (pysurface.ReadClasses).Related PRs
apps/plugins-repo.md), merged through the combined patch-it-dev/developer-handbook#40🤖 Generated with Claude Code