From edfa24b6a8fec8ef73bd8fcc4cc0861880b12f0f Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 20:50:55 -0500 Subject: [PATCH] plugin: a version can say which version of another source it pins Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- core/plugin/plugin_test.go | 9 +++++++++ core/plugin/versions.go | 16 ++++++++++++++++ docs/writing-a-plugin.md | 3 ++- 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/core/plugin/plugin_test.go b/core/plugin/plugin_test.go index bdd9063..d7681bd 100644 --- a/core/plugin/plugin_test.go +++ b/core/plugin/plugin_test.go @@ -82,3 +82,12 @@ func TestTwoSourcesCantShareAnID(t *testing.T) { }() register(t, "test-dup") } + +func TestAVersionPinsNothingUntilSet(t *testing.T) { + if !(Version{ID: "12.0.0"}).MapsTo.IsZero() { + t.Error("a version with no MapsTo pins something") + } + if (Pin{API: "example/api", Version: "2026-03-31"}).IsZero() { + t.Error("a set pin is zero") + } +} diff --git a/core/plugin/versions.go b/core/plugin/versions.go index ffc99ce..845dc50 100644 --- a/core/plugin/versions.go +++ b/core/plugin/versions.go @@ -43,8 +43,24 @@ type Version struct { // URL is where a person sees this version (a release page, a commit, a // Wayback Machine snapshot). URL string + // MapsTo is the version of another source this one pins, when it pins + // one: an SDK release and the API version it calls ("stripe/api", + // "2025-03-31"). Zero when it pins none or the source doesn't say. The + // plugin reads it from the release itself (its notes, the version + // constant in its code), never from a table kept by hand; it is how a + // feed query on the SDK's versions also gets the API's changes. + MapsTo Pin } +// Pin is one version of another source: what a release pins. +type Pin struct { + API string // the source's provider/source id: "stripe/api" + Version string // as that source names it: "2025-03-31" +} + +// IsZero is true when nothing is pinned. +func (p Pin) IsZero() bool { return p.API == "" && p.Version == "" } + // Snapshot is a source as it was at one version: what ReadAt or Read read. type Snapshot struct { Version Version diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 01b4ea7..cc405ef 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -116,7 +116,7 @@ type Env struct { } type Snapshot struct { - Version Version // ID, Released, Ref, URL + Version Version // ID, Released, Ref, URL, MapsTo (the other source's version it pins, if any) Content []byte SourceURL string // the exact document read: the events' citation CompareHash string // a living page only: how its next Read tells it unchanged @@ -137,6 +137,7 @@ When a release or a page has no part the reader can use (a changelog with no sec A source that has versions (a spec's releases, a package's releases, a guide per major, the commits that changed a file) is read version by version, so a customer several versions behind gets every step: the runner lists the versions, reads each consecutive pair with `ReadAt` and extracts it once (a released version never changes). - **List** with [`core/versions`](../core/versions/versions.go): `GitHubReleases`, `GitHubTags`, `GitHubCommits` (the commits that changed a file), `PyPIReleases`, `NPMReleases`, `GitHubPages` (any other GitHub list, page by page). An OpenAPI adapter lists its own versions (`adapter.Lister`): every adapter does. Never pin a tag in code: a version you need for a golden test is a pinned *case* in the test (`changelog.Urllib3.At("2.0.0")`), not the registered source. +- **Pins** (`Version.MapsTo`): when a release pins a version of another source (an SDK release and the API version it calls), set it while listing, from the release itself (its notes, the version constant in its code). It is how a feed query on the SDK's versions also returns the API's changes. Leave it zero when the release doesn't say: never fill it from a table kept by hand. - **Read at** a version's `Ref` (a tag, a commit SHA) and return the exact URL read as the snapshot's `SourceURL`: it's the events' citation. - **Extract** sets `previous_version` to `from`'s version: every `api_operation` and `package_release` event must name it (the contract's rule 13). `from` is zero only for the first version read, which has nothing to compare: patch-it's hosted ingestion service reads that version as its first snapshot and extracts nothing from it, so a version pair always starts at a real `from` (an `api_operation` or `package_release` event extracted from zero would be rejected).