Thanks for helping patch-it watch more APIs. This file is the rulebook; docs/writing-a-plugin.md is the how-to.
Start a new provider with the starter: make new-plugin ARGS='--provider <id> --source <id> --kind <kind>' (which kind?; in a terminal it asks for the rest) 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).
- 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 pluginsprints it, each release carries it asplugins.json, and docs.patch-it.dev reads it from there. Nothing else to update. - Fetch only through the environment. Plugins get their sources from
env.Getor the helpers incore/kit/, never fromnet/httpdirectly, the filesystem or a database. That keeps tests offline and lets the hosted service cache, retry and rate-limit politely. - Every plugin has a golden test over a real saved copy of its source:
testdata/<file>in,testdata/golden/<provider>-<source>.jsonout.testdata/README.mdlists 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. - 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.
- 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).
- Document the provider in
providers/<provider>-<source>.md, copied fromproviders/_template.md: what it watches, why you chose that source (and the alternatives you didn't), how the provider announces changes, what the plugin reads and ignores, and known gaps. - Nothing private. This repo is public. No credentials, tokens, internal hostnames or links to private repos or systems, in code, tests, commit messages or PR descriptions. CI scans every PR for secrets and for known internal names.
We use the Developer Certificate of Origin. Sign off every commit:
git commit -s -m "add the foo plugin"That adds Signed-off-by: Your Name <[email protected]>, matching the commit's author. CI_dco fails a PR with an unsigned commit. To fix one: git commit --amend -s (last commit) or git rebase --signoff origin/main (all of them), then force-push your branch.
- One plugin or one fix per PR. Fill in the PR template's checklist.
- Commit subjects: short, lowercase, imperative (
add the foo plugin,fix stripe hint parsing). - Run
make checkbefore you push. It runs exactly whatCI_goruns (tidy, build, gofmt, vet, the import allowlist, thenet/httpguard,go test -race) plus the internal-names check, so a greenmake checkmeans those CI checks pass. - A maintainer listed in
.github/CODEOWNERSreviews every PR. - Reviews: Claude also reviews each PR against the rules above, once, when it's opened or marked ready. PRs from forks get no secrets, so for those a maintainer comments
@claude reviewand Claude reviews it read-only (it never runs a fork's code). Only maintainers can call@claude. Claude's review helps; a maintainer still decides.
| Workflow | What it checks |
|---|---|
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 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 |
Release |
Not a check: tags a release on its own twice a week, or when a maintainer runs it (see Releasing) |
Releases are tags on main (v0.x.y), made only by the Release workflow. Nothing is tagged on push, and agents never tag or release.
Automatic, twice a week: every Monday and Thursday at 14:00 UTC the workflow makes a patch release, but only if something was merged since the last tag; otherwise it does nothing. If the merges add a new kind (a new plugins/<kind>/ directory), the scheduled run skips with a warning instead: run it by hand with minor. So a merged plugin reaches patch-it's hosted ingestion service within a few days.
By hand, any time (an urgent fix, or a minor release):
- Merge the PRs that should go out.
- Actions → Release → Run workflow (branch
main), pick the bump:- patch (
v0.4.1→v0.4.2): fixes, a new source on an existing kind, docs; - minor (
v0.4.1→v0.5.0): a new kind, new exported API, anything users should read about.
- patch (
- 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,gofmtandgo test -race. Any failure stops it before a tag exists. - 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). 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 readshttps://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.
Never delete or move a pushed tag. Go's module proxy and checksum database keep every published version forever, so a moved tag breaks everyone who already fetched it. If a release is wrong, fix it on main and release the next patch version.
By contributing you agree that your contribution is licensed under Apache-2.0.