Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions core/plugin/plugin_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
}
16 changes: 16 additions & 0 deletions core/plugin/versions.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand Down
Loading