patch-it-plugins

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0

README

patch-it-plugins

The source plugins for patch-it, the tool that turns third-party API changes into pull requests in your repo. Each plugin reads one provider's own sources (API specs, changelogs, deprecation pages, SDK migration guides, release feeds) and turns what changed into change events.

Just moved. The plugins were moved here from patch-it's hosted ingestion service, which imports this module at a tagged release (v0.x.y) and runs them every day.

How a plugin works

provider source ──fetch──▶ plugin ──▶ change events ──▶ patch-it's change feed ──▶ your CI
 (spec, page, feed)        reads, diffs,   (validated, each       (GET /v1/changes)       (patch-it opens
                           normalizes       with a source link                              the PR)
                                            and a quote)
  1. Fetch. The plugin asks its environment for the source (env.Get); it never opens connections itself. Pages that change in place are also cited through a Web Archive snapshot, so the link in an event keeps showing what the plugin read.
  2. Compare. It compares the source to the last version it saw (the baseline): two OpenAPI specs, two versions of a deprecations page, a new release's changelog section.
  3. Emit events. Each change becomes one event in patch-it's change-event format: what changed, how bad it is (breaking, deprecation, behavior change, non-breaking), the date it takes effect, and the source URL with a quote. No source, no event.

Plugins are small: most providers are an entry for a shared format plugin (openapi, retirements, migrationguide, removedmembers, changelog, feed), not new code. patch-it's hosted service runs every plugin daily and serves the events to the patch-it GitHub Action and CLI.

Layout

Path What's there
plugin/ The Plugin interface, the registry (Register, Lookup, Names), Env, Result
plugins/ The format plugins: openapi, retirements, migrationguide, removedmembers, changelog, feed. plugins/all imports every one
kit/, kit/kittest/ What plugins share (the unchanged-page check, Wayback citing) and the test kit (in-memory store, saved pages, golden files)
event/, migrate/ The change-event types of patch-it's contract, and the v1 → v2 conversion
diff/, normalize/, hint/, adapter/ The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider
retire/, sdkguide/, fetch/ The deprecations-page and migration-guide readers; the HTTP fetch and cache
contract/fixtures/ A copy of patch-it's change-event fixtures
providers/ One page per provider: why that source, what the plugin reads
docs/ The plugin list and how to write a plugin

Supported plugins

See docs/plugins.md. The same list is on docs.patch-it.dev.

Run the tests

Go (the version in go.mod), no other setup:

go build ./...
go vet ./...
gofmt -l .           # prints nothing when formatted
go test -race ./...

The tests are offline: every plugin's test reads a saved copy of its source from testdata/ and compares the events with a golden file. One package: go test ./plugins/feed. After an intended change to a plugin's output, go test ./plugins/<name> -update rewrites its golden files; review that diff like code.

Environment
Variable Needed What it does
GITHUB_TOKEN No Optional. A GitHub token (no scopes needed) sent to the GitHub API when the openapi adapters look up release tags (Stripe's and Datadog's releases, GitHub's API versions). It only raises GitHub's rate limit for unauthenticated calls (60 an hour per IP); the tests never use it.

Nothing else is read from the environment.

Contributing

New providers and fixes are welcome. Read CONTRIBUTING.md first (DCO sign-off, golden tests, adding your plugin to docs/plugins.md). AI coding agents: AGENTS.md.

User docs for patch-it itself: docs.patch-it.dev.

License

Apache-2.0, copyright patch-it contributors.

Directories

Path Synopsis
Package adapter defines the per-API source adapter interface and holds each API's adapter, starting with Stripe.
Package adapter defines the per-API source adapter interface and holds each API's adapter, starting with Stripe.
Package diff compares two OpenAPI specs and reports what structurally changed between them.
Package diff compares two OpenAPI specs and reports what structurally changed between them.
Package fetch does plain HTTP GETs with retries and a timeout.
Package fetch does plain HTTP GETs with retries and a timeout.
Package hint fills a change event's migration_hint from the vendor's own changelog.
Package hint fills a change event's migration_hint from the vendor's own changelog.
kit
Package kit is what source plugins share beyond the core: the Wayback Machine client a plugin cites a live page through (Wayback, Cite) and the "same page as last run" check (Unchanged).
Package kit is what source plugins share beyond the core: the Wayback Machine client a plugin cites a live page through (Wayback, Cite) and the "same page as last run" check (Unchanged).
kittest
Package kittest is the plugin test kit: a saved copy of a source in, the events a plugin stores out, compared with a golden file.
Package kittest is the plugin test kit: a saved copy of a source in, the events a plugin stores out, compared with a golden file.
Package migrate converts stored v1 change events to the proposed v2 contract (the change event contract): `affected` becomes a typed `subject`.
Package migrate converts stored v1 change events to the proposed v2 contract (the change event contract): `affected` becomes a typed `subject`.
Package normalize turns the differ's structural changes into change events: the one shape every downstream step consumes, defined in the change event contract (contract/README.md).
Package normalize turns the differ's structural changes into change events: the one shape every downstream step consumes, defined in the change event contract (contract/README.md).
Package plugin is what a change source is: every source is a plugin behind one interface, registered by name.
Package plugin is what a change source is: every source is a plugin behind one interface, registered by name.
plugins
all
Package all imports every plugin, so each registers itself: a program that runs plugins imports this one package.
Package all imports every plugin, so each registers itself: a program that runs plugins imports this one package.
changelog
Package changelog is the source plugin for a package's changelog file (CHANGELOG.md, CHANGES.rst, HISTORY.rst), read at a release's tag: one change event per bullet that plainly removes, renames or deprecates names code uses.
Package changelog is the source plugin for a package's changelog file (CHANGELOG.md, CHANGES.rst, HISTORY.rst), read at a release's tag: one change event per bullet that plainly removes, renames or deprecates names code uses.
feed
Package feed is the source plugin for a vendor's RSS or Atom changelog feed: one event per breaking or deprecation entry (or per name such an entry lists), quoting the line that says so.
Package feed is the source plugin for a vendor's RSS or Atom changelog feed: one event per breaking or deprecation entry (or per name such an entry lists), quoting the line that says so.
migrationguide
Package migrationguide is the source plugin for an SDK's migration guide, read at the release tag of the major it describes: an event per request parameter the release removed (sdkguide/).
Package migrationguide is the source plugin for an SDK's migration guide, read at the release tag of the major it describes: an event per request parameter the release removed (sdkguide/).
openapi
Package openapi is the source plugin for an API that publishes an OpenAPI spec per release (Stripe, Datadog, GitLab, GitHub): fetch the newest spec, diff it against the last one seen, normalize the changes into events, and attach migration hints from the API's changelog when it has one.
Package openapi is the source plugin for an API that publishes an OpenAPI spec per release (Stripe, Datadog, GitLab, GitHub): fetch the newest spec, diff it against the last one seen, normalize the changes into events, and attach migration hints from the API's changelog when it has one.
removedmembers
Package removedmembers is the source plugin for a package release that removed members of its top-level module, read from the release's own migration guide at its tag: change event v2's `package_release` subject .
Package removedmembers is the source plugin for a package release that removed members of its top-level module, read from the release's own migration guide at its tag: change event v2's `package_release` subject .
retirements
Package retirements is the source plugin for a model provider's deprecations page (OpenAI, Anthropic): every retired model becomes an event.
Package retirements is the source plugin for a model provider's deprecations page (OpenAI, Anthropic): every retired model becomes an event.
Package retire reads a model provider's deprecations page and turns every retired model into change events: a second kind of source next to the OpenAPI differ.
Package retire reads a model provider's deprecations page and turns every retired model into change events: a second kind of source next to the OpenAPI differ.
Package sdkguide reads an SDK's own migration guide for the request parameters a major release removed: a third kind of source, next to the OpenAPI differ and the deprecations pages.
Package sdkguide reads an SDK's own migration guide for the request parameters a major release removed: a third kind of source, next to the OpenAPI differ and the deprecations pages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL