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
4 changes: 2 additions & 2 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@

## Checklist

- [ ] **Added to / updated in `docs/plugins.md`** (new plugin: a row; changed id, provider, source, what it watches, format or status: the row updated; removed: the row removed). Not applicable: <!-- say why -->
- [ ] **Metadata complete in the registration** (`plugin.RegisterProvider`: provider id, name, category, homepage; each source's id, layer, what it watches, URLs, page), and I read the words. There is no list to update. Not applicable: <!-- say why -->
- [ ] Every commit is signed off (`git commit -s`, DCO)
- [ ] Golden test over a real saved copy of the source (`testdata/golden/<api>.json`)
- [ ] `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` / `core/kit/`
- [ ] `make check` passes locally (and `make plugins-json` was run if a plugin or its row changed)
- [ ] `make check` passes locally (`make plugins` prints the source as you expect)
- [ ] Nothing private: no credentials, internal hosts, private links, customer names

## Notes for the reviewer
Expand Down
1 change: 0 additions & 1 deletion .github/workflows/CI_go.yml
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,6 @@ jobs:
run: make todos

# -race: the fetcher and the tests' HTTP servers run on other goroutines.
# Also fails when docs/plugins.json is out of date (make plugins-json).
- name: go test
if: steps.go.outputs.present == 'true'
run: make test
12 changes: 6 additions & 6 deletions .github/workflows/claude-code-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,12 +93,12 @@ jobs:
any issue it references with `gh issue view <number>`. Read the diff with
`gh pr diff <PR NUMBER>`, and changed files in full where the diff isn't
enough context.
2. THE PLUGIN LIST (AGENTS.md Rule 1). Every plugin added, removed, or with a
changed id, provider, source, what it watches, format plugin or status has
its row added, removed or updated in docs/plugins.md, between the
`<!-- plugins:start -->` and `<!-- plugins:end -->` markers, as a plain
Markdown table with absolute links only. Compare the registered plugins with
the table yourself; a missing row is blocking.
2. THE METADATA (AGENTS.md Rule 1). Every source added or changed is
registered with plugin.RegisterProvider with complete, accurate metadata:
the provider's id, name, category and homepage; each source's id, layer,
what it watches, the URLs it reads and its page. There is no hand-kept list
(no docs/plugins.md, no plugins.json in the repo): one reappearing is
blocking.
3. PROVIDER PAGE. Every new provider has providers/<api>.md copied from
providers/_template.md, with a real **Why this source**: the link, the date
it was checked, why it's the best source, the alternatives not used, and a
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 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."
--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 or changed source is registered with plugin.RegisterProvider with complete, accurate metadata (provider id, name, category, homepage; source id, layer, what it watches, URLs, page), and no hand-kept list of plugins comes back; (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."
11 changes: 10 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -172,9 +172,18 @@ jobs:
git tag -a "$TAG" "$SHA" -m "$TAG" -m "Released by the Release workflow ($by)."
git push origin "refs/tags/$TAG"

# The list of providers and sources, from the registry at the tag: the
# release's plugins.json asset. Never committed; the docs site reads the
# latest release's copy.
- name: list the providers and sources
if: steps.version.outputs.skip != 'true'
env:
TAG: ${{ steps.version.outputs.tag }}
run: go run ./cmd/list-plugins -ref "$TAG" -o "$RUNNER_TEMP/plugins.json"

- name: publish the GitHub release
if: steps.version.outputs.skip != 'true'
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ steps.version.outputs.tag }}
run: gh release create "$TAG" --verify-tag --generate-notes --title "$TAG"
run: gh release create "$TAG" --verify-tag --generate-notes --title "$TAG" "$RUNNER_TEMP/plugins.json"
17 changes: 7 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,11 @@

Rules for AI coding agents (and humans) working in this repo. `CLAUDE.md` imports this file.

## Rule 1: every new or changed plugin goes in `docs/plugins.md`
## Rule 1: every new or changed provider or source has complete metadata in its registration

**If you add a plugin, add its row to [`docs/plugins.md`](docs/plugins.md) in the same PR. If you change a plugin's id, provider, source, what it watches, format plugin or status, update its row in the same PR. If you remove one, remove its row.**
**A source exists when its kind's package registers it with `plugin.RegisterProvider`, and its metadata lives only there: the provider's id, name, category and homepage, and each source's id, layer, what it watches, the URLs it reads and its page, `providers/<name>.md`.** Adding, changing or removing a source is a change to that registration (and to its page) in the same PR. There is no list to update: nothing in this repo, the docs site or anywhere else keeps one by hand.

The list of supported APIs on docs.patch-it.dev is generated from that file, so a plugin missing from it doesn't exist as far as users can tell. Then run `make plugins-json`: it regenerates [`docs/plugins.json`](docs/plugins.json) from the plugin registry and the table (and the plugin count on the README's badge), and fails if a registered plugin has no row (or a row has no plugin, a wrong format or no provider page). `go test` fails while `docs/plugins.json` is out of date. The check can't tell whether a row's words are right: you are that check. Say in the PR that you compared them.

Keep the table between the `<!-- plugins:start -->` and `<!-- plugins:end -->` markers a plain Markdown table, one row per plugin, absolute links only (the docs site copies it verbatim).
`go run ./cmd/list-plugins` prints the list from the registry (JSON), and the Release workflow attaches it to every release as `plugins.json`; the docs site and patch-it's hosted ingestion service read it from there. `RegisterProvider` refuses incomplete metadata and `go test` fails when a source's page is missing, but no check can tell whether the words are right: you are that check. Say in the PR that you read them.

## Rule 2: this repo is public

Expand Down Expand Up @@ -41,7 +39,7 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser
```sh
make check # tidy, build, gofmt, vet, the import allowlist, the net/http guard, go test -race, no TODO(new-plugin) left, leak guard
make check PATCH_IT=../patch-it # also CI_contract: contract/fixtures/ against a patch-it checkout
make plugins-json # regenerate docs/plugins.json after adding or changing a plugin or its row
make plugins # print the list of providers and sources from the registry (what each release attaches as plugins.json)
```

One target at a time: `make tidy`, `make build`, `make fmt`, `make vet`, `make imports`, `make nethttp`, `make test`, `make todos`, `make leak-guard`, `make contract`. Use `make GO=/path/to/go check` for another Go.
Expand All @@ -63,11 +61,10 @@ plugins/<kind>/ one package per kind, with its providers: openapi (+ adap
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/list-plugins/ prints the list from the registry (make plugins); internal/pluginlist/ is its logic
cmd/new-plugin/ scaffolds a provider on a format plugin (go run ./cmd/new-plugin --help)
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
Makefile make check (what CI_go runs, plus the leak guard), make plugins
docs/ contributor docs, including writing-a-plugin.md
providers/<api>.md one page per provider
scripts/ leak_guard.py (hashed internal names), check_contract.py
Expand All @@ -81,7 +78,7 @@ The [change-event contract](https://github.com/patch-it-dev/patch-it/tree/main/d

- Sign off every commit: `git commit -s` (DCO; `CI_dco` checks it).
- Subjects short, lowercase, imperative: `add the foo plugin`.
- One plugin or fix per PR; fill in every checkbox of the PR template, including "added to docs/plugins.md".
- One plugin or fix per PR; fill in every checkbox of the PR template, including "metadata complete in the registration".
- AI-assisted commits keep their co-author trailer.
- Never re-run, dispatch or retrigger CI to "see if it passes"; fix the cause and push.

Expand Down
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

Thanks for helping patch-it watch more APIs. This file is the rulebook; [docs/writing-a-plugin.md](docs/writing-a-plugin.md) is the how-to.

**Start a new provider with the starter:** `go run ./cmd/new-plugin --api <id> --provider <Name> --format <format>` writes the definition, its registration, a test over placeholder sources, the testdata rows, the provider page and the `docs/plugins.md` row; you fill in the `TODO(new-plugin)`s ([how](docs/writing-a-plugin.md#1-scaffold-it-with-new-plugin)).
**Start a new provider with the starter:** `go run ./cmd/new-plugin --api <id> --provider <Name> --format <format>` writes the definition, its registration, a test over placeholder sources, the testdata rows, the provider page, and the source's metadata in its `RegisterProvider` block; you fill in the `TODO(new-plugin)`s ([how](docs/writing-a-plugin.md#1-scaffold-it-with-new-plugin)).

## 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.
1. **Give every provider and source complete metadata in its registration.** A source exists when its kind's package registers it with `plugin.RegisterProvider`: the provider's id, name, category and homepage, and the source's id, layer, what it watches, the URLs it reads and its page. That registration is the only list: `make plugins` prints it, each release carries it as `plugins.json`, and docs.patch-it.dev reads it from there. Nothing else to update.
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.
Expand Down Expand Up @@ -36,7 +36,7 @@ That adds `Signed-off-by: Your Name <[email protected]>`, matching the commit's au

| Workflow | What it checks |
|---|---|
| `CI_go` | `go mod tidy`, build, vet, gofmt, `go test -race` (including that `docs/plugins.json` is up to date); plugins import only this module, the standard library and approved dependencies; `net/http` only in the fetch layer. Each step is a [Makefile](Makefile) target: `make check` runs them all locally |
| `CI_go` | `go mod tidy`, build, vet, gofmt, `go test -race` (including that every registered source has its metadata and page); plugins import only this module, the standard library and approved dependencies; `net/http` only in the fetch layer. Each step is a [Makefile](Makefile) target: `make check` runs them all locally |
| `CI_dco` | Every commit in the PR is signed off by its author |
| `CI_leak_guard` | gitleaks over the PR's commits, and a check for known internal names (stored as hashes only). Also runs weekly over the whole repo |
| `Claude Code Review` | Claude reviews the PR against the rules above, once (PRs from this repo's branches; forks: a maintainer comments `@claude review`). Advisory, not a required check |
Expand All @@ -55,7 +55,7 @@ Releases are tags on `main` (`v0.x.y`), made only by the **Release** workflow. N
- **patch** (`v0.4.1` → `v0.4.2`): fixes, a new provider on an existing format plugin, docs;
- **minor** (`v0.4.1` → `v0.5.0`): a new format plugin, new exported API, anything users should read about.
3. The workflow refuses if `main`'s HEAD is already tagged, then runs, on that exact commit, the internal-names check over every file, gitleaks over the whole history, `go build`, `go vet`, `gofmt` and `go test -race`. Any failure stops it before a tag exists.
4. When everything passes it pushes an annotated tag and publishes a GitHub release with generated notes (grouped by the PR's label: `plugin`/`enhancement`, `bug`, `documentation`; see [`.github/release.yml`](.github/release.yml)).
4. When everything passes it pushes an annotated tag and publishes a GitHub release with generated notes (grouped by the PR's label: `plugin`/`enhancement`, `bug`, `documentation`; see [`.github/release.yml`](.github/release.yml)). The release carries one asset, `plugins.json`: the list of providers and sources printed from the registry at that tag (`go run ./cmd/list-plugins`). It is the only published list; nothing in the repo keeps one, and docs.patch-it.dev reads `https://github.com/patch-it-dev/patch-it-plugins/releases/latest/download/plugins.json`.

`v1.0.0` (and any later major) is not a button: it is a deliberate decision a maintainer makes and tags by hand.

Expand Down
13 changes: 7 additions & 6 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
#
# make check everything below, in CI's order
# make check PATCH_IT=../patch-it also compare contract/fixtures/ with patch-it's
# make plugins-json regenerate docs/plugins.json from the registry and docs/plugins.md
# make plugins print the providers and sources from the registry (JSON)
#
# The `::error` lines are GitHub annotations; locally they're plain messages.

Expand All @@ -17,7 +17,7 @@ PYTHON ?= python3
MODULE := github.com/patch-it-dev/patch-it-plugins
ALLOWED := ^($(MODULE)(/|$$)|gopkg\.in/yaml\.v3$$)

.PHONY: check tidy build fmt vet imports nethttp test todos leak-guard contract plugins-json
.PHONY: check tidy build fmt vet imports nethttp test todos leak-guard contract plugins

check: tidy build fmt vet imports nethttp test todos leak-guard contract
@echo "make check: all passed"
Expand Down Expand Up @@ -58,13 +58,12 @@ nethttp:
fi

# -race: the fetcher and the tests' HTTP servers run on other goroutines.
# Includes the check that docs/plugins.json is up to date (internal/pluginlist).
test:
$(GO) test -race -count=1 ./...

# A provider started with new-plugin is done when nothing it wrote still says
# TODO(new-plugin).
TODO_DIRS := plugins core/migrate providers docs/plugins.md
TODO_DIRS := plugins core/migrate providers
todos:
@left=$$(grep -rl 'TODO(new-plugin)' $(TODO_DIRS) || true); \
if [ -n "$$left" ]; then \
Expand All @@ -87,5 +86,7 @@ contract:
echo "contract: skipped (make check PATCH_IT=<a patch-it checkout> compares contract/fixtures/)"; \
fi

plugins-json:
$(GO) run ./cmd/list-plugins
# The list of what patch-it watches, from the registry. Never committed: the
# Release workflow attaches it to each release as plugins.json.
plugins:
@$(GO) run ./cmd/list-plugins
Loading
Loading