Skip to content

plugin: a version can say which version of another source it pins - #226

Open
adssib wants to merge 1 commit into
mainfrom
pl-maps-to
Open

adssib wants to merge 1 commit into
mainfrom
pl-maps-to

Conversation

@adssib

@adssib adssib commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

What this changes

Adds one field to plugin.Version: MapsTo plugin.Pin (API, Version), the version of another source a release pins, e.g. an SDK release and the API version it calls (stripe/api 2025-03-31). Zero when the release pins nothing or doesn't say.

The change feed contract (patch-it docs/contract/change-feed-api.md, "From and to") now has the server map a package version to what it pins, and GET /v1/plugins/{provider}/{source}/versions shows it as maps_to. The server has no table of what an SDK release pins, so the data has to come from the plugin that lists the versions: this is the minimal field for that. No plugin fills it yet; a source that can read it from its releases (the release notes or the version constant in the code) sets it in ListVersions, in its own PR.

  • core/plugin/versions.go: Version.MapsTo, Pin, Pin.IsZero
  • docs/writing-a-plugin.md: how and when to set it (from the release itself, never a hand-kept table)
  • one test

Checklist

  • Metadata complete in the registration: Not applicable: no source added or changed.
  • Every commit is signed off (git commit -s, DCO)
  • Golden test: not applicable, no plugin output changes
  • testdata/README.md: not applicable
  • Drop test: not applicable
  • providers/<provider>-<source>.md: not applicable
  • Fetches only through env.Get / core/kit/ (no fetching added)
  • make check passes locally
  • Nothing private

Notes for the reviewer

  • Pin is a plain comparable struct, so plugin.Version stays comparable (kittest compares it with ==).
  • Needs a release (vX.Y.Z) before patch-it's hosted ingestion service can read it: its bump PR then copies MapsTo into the version rows it stores.

🤖 Generated with Claude Code

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 52s —— View job


✅ Ready to merge: a small, additive field on plugin.Version with no effect on existing output, and everything builds and passes.

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) N/A No source added or changed, and no hand-kept list added
Provider page N/A No provider touched
Golden test + dated quote N/A No plugin output changes, and no golden or testdata files are touched
Drop test N/A No plugin
Fetch only via env ✅ No fetching, net/http or filesystem access added
contract/fixtures/ untouched ✅ Not in the diff
Nothing private (Rule 2) ✅ Diff, PR body and commit message checked. Leak guard is clean. The example stripe/api / 2025-03-31 is a public API version.
DCO ✅ The commit has Signed-off-by and keeps its co-author trailer

Bugs

None found.

  • Pin has only string fields, so plugin.Version can still be compared with ==. Both places that rely on this still work: kittest.go:82 (from != (plugin.Version{})) and kittest.go:132 (again.Version != cur.Version).
  • Every existing plugin.Version{...} literal uses field names, including core/versions and the cmd/new-plugin templates. Adding a field doesn't break any of them, and go build confirms it.

Verified

  • go build ./...: OK
  • go vet ./...: OK
  • gofmt -l .: printed nothing
  • go test -race ./...: every package ok, including core/plugin with the new test
  • python3 scripts/leak_guard.py --all: no banned terms (8 hashed terms checked)

Non-blocking (optional)

  • A half-set pin isn't zero. Pin{API: "stripe/api"} with no Version makes IsZero() return false, so a plugin could hand the server a pin that is only half filled in. When the first plugin starts filling MapsTo, it would help to reject this in one place, for example a Pin.Valid() that needs both fields or neither. Ideally that check also makes sure API names a source in the registry. kittest.Versions or the runner could call it so a typo like "stripe/apis" fails in tests rather than in the hosted ingestion service.
  • The field name API could mislead. It holds a provider/source id, which is the same thing event.API holds, so the naming is consistent. Still, a reader might expect the API's name here. The inline comment already explains it, so this is fine as written.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant