Skip to content
Merged
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
2 changes: 1 addition & 1 deletion .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
- [ ] `testdata/README.md` lists each file: URL, date fetched, license, quote of the part the plugin reads
- [ ] One pinned drop test: a realistic input that produces no event
- [ ] `providers/<api>.md` written or updated from `providers/_template.md`, including **Why this source**
- [ ] Fetches only through `env.Get` / `kit/`
- [ ] Fetches only through `env.Get` / `core/kit/`
- [ ] `make check` passes locally (and `make plugins-json` was run if a plugin or its row changed)
- [ ] Nothing private: no credentials, internal hosts, private links, customer names

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/CI_contract.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# contract/fixtures/ is a copy of patch-it's fixtures/ (the change-event contract
# patch-it owns). This fails when the two drift apart, so event/ and migrate/ test
# patch-it owns). This fails when the two drift apart, so core/event/ and core/migrate/ test
# the same events the patch-it client does. Only top-level "_comment" fields may
# differ (scripts/check_contract.py).
#
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/CI_go.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# The plugins build, are formatted and vetted, and their tests pass with the race
# detector. Two guards keep plugins self-contained:
# - imports: only this module, the standard library and the approved dependencies;
# - network: net/http only in the fetch layer (fetch/, kit/, adapter/).
# - network: net/http only in the fetch layer (core/fetch/, core/kit/, plugins/openapi/adapter/).
# The steps are Makefile targets, so `make check` runs exactly this locally.
# Until the Go code lands there is no go.mod, and every step after the first is skipped
# with a notice, so the check passes.
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/claude-code-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ jobs:
the source URL and a quote. A golden file edited without the PR explaining
why the new output is right is blocking.
5. PLUGIN CODE. Fetch only through env.Get or kit/: no net/http outside the
fetch layer (fetch/, kit/, adapter/), no filesystem outside testdata/, no
fetch layer (core/fetch/, core/kit/, plugins/openapi/adapter/), no filesystem outside testdata/, no
database. Precision over recall: flag any path that could emit an event for
something that isn't a real change; a wrong event becomes a wrong pull
request in someone's repo. Don't change contract/fixtures/ here first (the
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/claude.yml
Original file line number Diff line number Diff line change
Expand Up @@ -68,4 +68,4 @@ jobs:
--permission-mode default
--allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*)"
--disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*),Bash(git add:*),Bash(git rm:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files"
--append-system-prompt "This is patch-it-plugins, a public repo of source plugins. Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check it against AGENTS.md: (1) every new, changed or removed plugin has its row added, updated or removed in docs/plugins.md between the plugins:start and plugins:end markers, absolute links only; (2) every new provider has providers/<api>.md from providers/_template.md with a real 'Why this source' (link, date checked, why it's best, alternatives, quote); (3) a golden test over a real saved source, a testdata/README.md row (URL, date fetched, license, quote), one pinned drop test, every event carries its source URL and a quote, and golden edits are explained; (4) fetch only through env.Get or kit/, no net/http outside fetch/, kit/ and adapter/, no filesystem outside testdata/; (5) precision over recall: flag anything that could emit an event for a non-change; (6) nothing private: no credentials, internal hostnames or service names, links to private repos or tickets, customer names, or links to AI sessions. You can't run the tests; say that CI_go covers them. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then a table of rule | status | evidence, blocking bugs, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link."
--append-system-prompt "This is patch-it-plugins, a public repo of source plugins. Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check it against AGENTS.md: (1) every new, changed or removed plugin has its row added, updated or removed in docs/plugins.md between the plugins:start and plugins:end markers, absolute links only; (2) every new provider has providers/<api>.md from providers/_template.md with a real 'Why this source' (link, date checked, why it's best, alternatives, quote); (3) a golden test over a real saved source, a testdata/README.md row (URL, date fetched, license, quote), one pinned drop test, every event carries its source URL and a quote, and golden edits are explained; (4) fetch only through env.Get or core/kit/, no net/http outside core/fetch/, core/kit/ and plugins/openapi/adapter/, no filesystem outside testdata/; (5) precision over recall: flag anything that could emit an event for a non-change; (6) nothing private: no credentials, internal hostnames or service names, links to private repos or tickets, customer names, or links to AI sessions. You can't run the tests; say that CI_go covers them. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then a table of rule | status | evidence, blocking bugs, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link."
22 changes: 13 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser
## Rules for plugin code

- **Start a new provider with `go run ./cmd/new-plugin --api <id> --provider <Name> --format <format>`**, then fill in every `TODO(new-plugin)`; `make todos` (part of `make check` and CI_go) fails while one is left.
- **Fetch only through the environment** (`env.Get` or `kit/`). No `net/http` outside the fetch layer, no filesystem outside `testdata/`, no database.
- **Fetch only through the environment** (`env.Get` or `core/kit/`). No `net/http` outside the fetch layer, no filesystem outside `testdata/`, no database.
- **Golden test + dated source quote**: a saved copy of the real source in `testdata/`, a row in `testdata/README.md` (URL, date fetched, license, quote), and `testdata/golden/<api>.json` with the exact events.
- **Precision over recall.** When unsure whether something is a change, don't emit an event.
- **One pinned drop test** per plugin: a realistic input that must produce no event.
Expand All @@ -51,16 +51,20 @@ One target at a time: `make tidy`, `make build`, `make fmt`, `make vet`, `make i
Go module `github.com/patch-it-dev/patch-it-plugins`; the only dependency is `gopkg.in/yaml.v3`.

```
plugin/ the Plugin interface, the registry, Env, Result, Spec (baselines)
core/plugin/ the Plugin interface, the registry, Env, Result, Spec (baselines)
core/fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache
core/github/ the newest release / commit on GitHub, and a commit's SHA and date (one place)
core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden)
core/event/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2
core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers
plugins/<kind>/ one package per kind, with its providers: openapi (+ adapter/, one spec adapter
per provider), retirements (+ retire/), migrationguide (+ sdkguide/),
removedmembers, changelog, feed, apichangelog, catalog, eol;
plugins/all imports every one
plugin/ event/ fetch/ migrate/ kit/ retire/ sdkguide/ deprecated old import paths: they only
forward to the packages above; don't add to them
cmd/list-plugins/ writes docs/plugins.json (make plugins-json); internal/pluginlist/ is its logic
cmd/new-plugin/ scaffolds a provider on a format plugin (go run ./cmd/new-plugin --help)
plugins/<format>/ one package per format plugin: openapi, retirements, migrationguide,
removedmembers, changelog, feed, apichangelog, catalog; plugins/all imports every one
kit/ kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden)
event/ migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2
fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache
diff/ normalize/ hint/ adapter/ the OpenAPI diff engine and the spec adapters
retire/ sdkguide/ deprecations-page and migration-guide readers
contract/fixtures/ a copy of patch-it's change-event fixtures (CI_contract checks it)
docs/plugins.md the list of supported plugins (Rule 1); docs/plugins.json is generated from it
Makefile make check (what CI_go runs, plus the leak guard), make plugins-json
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Thanks for helping patch-it watch more APIs. This file is the rulebook; [docs/wr
## The rules

1. **Add your plugin to [docs/plugins.md](docs/plugins.md).** Every new plugin gets a row; every change to a plugin's id, provider, source, what it watches or status updates its row. The list on docs.patch-it.dev is built from that file, so a plugin that isn't listed is invisible to users. Then run `make plugins-json` to regenerate [`docs/plugins.json`](docs/plugins.json); it fails if the registry and the table disagree, and the tests fail while the JSON is out of date.
2. **Fetch only through the environment.** Plugins get their sources from `env.Get` or the helpers in `kit/`, never from `net/http` directly, the filesystem or a database. That keeps tests offline and lets the hosted service cache, retry and rate-limit politely.
2. **Fetch only through the environment.** Plugins get their sources from `env.Get` or the helpers in `core/kit/`, never from `net/http` directly, the filesystem or a database. That keeps tests offline and lets the hosted service cache, retry and rate-limit politely.
3. **Every plugin has a golden test** over a real saved copy of its source: `testdata/<file>` in, `testdata/golden/<api>.json` out. `testdata/README.md` lists each file with its URL, the date you fetched it, its license, and a short quote of the part your plugin reads. Keep openly licensed files whole; trim vendor documentation pages to what the test needs.
4. **Precision over recall.** A missed change is a bug we can fix later. A wrong change becomes a wrong pull request in someone's repo. When in doubt, don't emit.
5. **One pinned drop test per plugin**: a realistic input your plugin must *not* turn into an event (an unrelated section, a renamed heading, a non-breaking addition).
Expand Down
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ imports:
nethttp:
@bad=$$($(GO) list -f '{{.ImportPath}} {{join .Imports " "}}' ./... \
| grep -E '(^| )net/http( |$$)' | cut -d' ' -f1 \
| grep -vE '^$(MODULE)/(fetch|kit|adapter)(/|$$)' || true); \
| grep -vE '^$(MODULE)/(core/fetch|core/kit|plugins/openapi/adapter)(/|$$)' || true); \
if [ -n "$$bad" ]; then \
echo "::error::these packages import net/http; fetch through env.Get or kit instead:"; echo "$$bad"; exit 1; \
fi
Expand All @@ -64,7 +64,7 @@ test:

# A provider started with new-plugin is done when nothing it wrote still says
# TODO(new-plugin).
TODO_DIRS := plugins adapter retire sdkguide migrate providers docs/plugins.md
TODO_DIRS := plugins core/migrate providers docs/plugins.md
todos:
@left=$$(grep -rl 'TODO(new-plugin)' $(TODO_DIRS) || true); \
if [ -n "$$left" ]; then \
Expand Down
13 changes: 7 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
[![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins)
[![Go version](https://img.shields.io/github/go-mod/go-version/patch-it-dev/patch-it-plugins)](go.mod)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-3f5bf0)](LICENSE)
[![Plugins](https://img.shields.io/badge/plugins-29-3f5bf0)](docs/plugins.md)
[![Plugins](https://img.shields.io/badge/plugins-30-3f5bf0)](docs/plugins.md)
[![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev)
[![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions)

Expand Down Expand Up @@ -96,14 +96,15 @@ Most providers are an entry for a shared format plugin (`openapi`, `retirements`

| Path | What's there |
|---|---|
| [`plugin/`](plugin/) | The `Plugin` interface, the registry (`Register`, `Lookup`, `Names`), `Env`, `Result` |
| [`core/plugin/`](core/plugin/) | The `Plugin` interface, the registry (`Register`, `Lookup`, `Names`), `Env`, `Result` |
| [`plugins/`](plugins/) | The format plugins; `plugins/all` imports every one |
| [`cmd/new-plugin/`](cmd/new-plugin/), [`cmd/list-plugins/`](cmd/list-plugins/) | The starter for a new provider; the generator of `docs/plugins.json` |
| [`kit/`](kit/), [`kit/kittest/`](kit/kittest/) | What plugins share (the unchanged-page check, Wayback citing) and the test kit (in-memory store, saved pages, golden files) |
| [`event/`](event/), [`migrate/`](migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion |
| [`diff/`](diff/), [`normalize/`](normalize/), [`hint/`](hint/), [`adapter/`](adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider |
| [`retire/`](retire/), [`sdkguide/`](sdkguide/), [`fetch/`](fetch/) | The deprecations-page and migration-guide readers; the HTTP fetch and cache |
| [`core/kit/`](core/kit/), [`core/kit/kittest/`](core/kit/kittest/), [`core/github/`](core/github/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub) and the test kit (in-memory store, saved pages, golden files) |
| [`core/event/`](core/event/), [`core/migrate/`](core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion |
| [`core/diff/`](core/diff/), [`core/normalize/`](core/normalize/), [`core/hint/`](core/hint/), [`plugins/openapi/adapter/`](plugins/openapi/adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider |
| [`plugins/retirements/retire/`](plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](plugins/migrationguide/sdkguide/), [`core/fetch/`](core/fetch/) | The deprecations-page and migration-guide readers; the HTTP fetch and cache |
| [`contract/fixtures/`](contract/) | A copy of patch-it's change-event fixtures |
| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves |
| [`providers/`](providers/) | One page per provider: why that source, what the plugin reads |
| [`docs/`](docs/) | [The plugin list](docs/plugins.md), [how to write a plugin](docs/writing-a-plugin.md), the [README template](docs/README-template.md) patch-it's public repos share |

Expand Down
Loading
Loading