From 3d0b90a1f2aac99e2915c1fa1c6dbaf68f8927f4 Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 18:12:40 -0500 Subject: [PATCH] new-plugin scaffolds a provider's source on a kind; which-kind guide --provider/--name/--category/--homepage, --source/--kind/--reader/--layer, --url and --package (repeatable), asked for in a terminal when missing; every kind and reader scaffolds (apisurface included, an OpenAPI adapter gets its Versions stub), plugins/all gets a new kind's import, and the old --format flags keep working for one release. make new-plugin ARGS=. docs/which-kind.md asks which kind a source is; a test checks every registered source's kind is one of its answers. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- AGENTS.md | 5 +- CONTRIBUTING.md | 8 +- Makefile | 9 +- README.md | 10 +- cmd/new-plugin/formats.go | 125 +++++++++++++++- cmd/new-plugin/main.go | 289 +++++++++++++++++++++++++++++------- cmd/new-plugin/main_test.go | 71 ++++++--- cmd/new-plugin/resolve.go | 170 +++++++++++++++++++++ docs/which-kind.md | 24 +++ docs/writing-a-plugin.md | 33 ++-- plugins/all/all_test.go | 14 ++ providers/algolia.md | 2 +- providers/anthropic.md | 2 +- providers/appwrite.md | 2 +- providers/convex.md | 2 +- providers/datadog.md | 2 +- providers/elasticsearch.md | 2 +- providers/flagsmith.md | 2 +- providers/github.md | 2 +- providers/gitlab.md | 2 +- providers/neon.md | 2 +- providers/planetscale.md | 2 +- providers/redis.md | 2 +- providers/sentry.md | 2 +- providers/stripe.md | 2 +- providers/supabase.md | 2 +- providers/textual.md | 2 +- providers/urllib3.md | 2 +- providers/vercel.md | 2 +- 29 files changed, 671 insertions(+), 123 deletions(-) create mode 100644 cmd/new-plugin/resolve.go create mode 100644 docs/which-kind.md diff --git a/AGENTS.md b/AGENTS.md index c37e6bc..249fac1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,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 --provider --format `**, then fill in every `TODO(new-plugin)`; `make todos` (part of `make check` and CI_go) fails while one is left. +- **Start a new source with `make new-plugin ARGS='--provider --name --source --kind '`** (`go run ./cmd/new-plugin`; [which kind](docs/which-kind.md)), 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 `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/.json` with the exact events. - **Precision over recall.** When unsure whether something is a change, don't emit an event. @@ -40,6 +40,7 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser 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 # print the list of providers and sources from the registry (what each release attaches as plugins.json) +make new-plugin ARGS='--provider acme --source api --kind openapi' # scaffold a source (asks for what's missing in a terminal) ``` 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. @@ -66,7 +67,7 @@ plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merg 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/ 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) +cmd/new-plugin/ scaffolds a provider's source on a kind (make new-plugin ARGS=...; go run ./cmd/new-plugin --help) contract/fixtures/ a copy of patch-it's change-event fixtures (CI_contract checks it) Makefile make check (what CI_go runs, plus the leak guard), make plugins docs/ contributor docs, including writing-a-plugin.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8554f02..10dfee1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ 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 --provider --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)). +**Start a new provider with the starter:** `make new-plugin ARGS='--provider --source --kind '` ([which kind?](docs/which-kind.md); 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](docs/writing-a-plugin.md#1-scaffold-it-with-new-plugin)). ## The rules @@ -46,14 +46,14 @@ That adds `Signed-off-by: Your Name `, matching the commit's au 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 format plugin** (a new `plugins//` 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. +**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//` 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): 1. Merge the PRs that should go out. 2. **Actions → Release → Run workflow** (branch `main`), pick the bump: - - **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. + - **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. 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)). 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`. diff --git a/Makefile b/Makefile index 5aa7bcd..3cd0e17 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,8 @@ # make check everything below, in CI's order # make check PATCH_IT=../patch-it also compare contract/fixtures/ with patch-it's # make plugins print the providers and sources from the registry (JSON) +# make new-plugin ARGS='--provider acme --source api --kind openapi' +# scaffold a source (cmd/new-plugin; asks for what's missing) # # The `::error` lines are GitHub annotations; locally they're plain messages. @@ -17,7 +19,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 +.PHONY: check tidy build fmt vet imports nethttp test todos leak-guard contract plugins new-plugin check: tidy build fmt vet imports nethttp test todos leak-guard contract @echo "make check: all passed" @@ -90,3 +92,8 @@ contract: # Release workflow attaches it to each release as plugins.json. plugins: @$(GO) run ./cmd/list-plugins + +# Scaffold a provider's source on a kind: cmd/new-plugin with ARGS. In a +# terminal it asks for whatever ARGS leaves out. +new-plugin: + $(GO) run ./cmd/new-plugin $(ARGS) diff --git a/README.md b/README.md index 9b8da30..5df0e49 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ You need Go (the version in `go.mod`), `make` and Python 3. -1. **Scaffold it**, on the kind that reads its source ([which kind](docs/writing-a-plugin.md#3-pick-the-kind)): +1. **Scaffold it**, on the kind that reads its source ([which kind?](docs/which-kind.md)); in a terminal, `make new-plugin` asks for what's missing: ```sh - go run ./cmd/new-plugin --api acme --provider Acme --format feed --source https://acme.example/changelog.xml + make new-plugin ARGS='--provider acme --name Acme --source api --kind notices --reader feed --url https://acme.example/changelog.xml' ``` -2. **Fill in every `TODO(new-plugin)`**: the reader, the provider and source metadata in its `plugin.RegisterProvider` block, a saved copy of the source in `testdata/`, and "Why this source" in `providers/acme.md`. Then write the golden file and read it like code: +2. **Fill in every `TODO(new-plugin)`**: the reader, the provider and source metadata in its `plugin.RegisterProvider` block, a saved copy of the source in `testdata/`, and "Why this source" in `providers/acme-api.md`. Then write the golden file and read it like code: ```sh - go test ./plugins/notices -run TestAcme -update + go test ./plugins/notices -run TestAcmeApi -update ``` 3. **Check it the way CI will, and open the PR** (`git commit -s`, one provider per PR): ```sh @@ -30,7 +30,7 @@ You need Go (the version in `go.mod`), `make` and Python 3. ## More -- [How to write a plugin](docs/writing-a-plugin.md): providers, sources, kinds, versions, the test kit, step by step. +- [Which kind fits my provider?](docs/which-kind.md) and [how to write a plugin](docs/writing-a-plugin.md): providers, sources, kinds, versions, the test kit, step by step. - [How it works](docs/how-it-works.md): what a plugin does, the layout, the checks, releases. - What's covered: `make plugins` prints every provider and source from the code; each [release](https://github.com/patch-it-dev/patch-it-plugins/releases) carries it as `plugins.json`, and [docs.patch-it.dev](https://docs.patch-it.dev/supported-apis/plugins/) shows it. - [CONTRIBUTING.md](CONTRIBUTING.md) (the rules), [AGENTS.md](AGENTS.md) (for AI coding agents), [Discussions](https://github.com/patch-it-dev/patch-it-plugins/discussions), [good first issues](https://github.com/patch-it-dev/patch-it-plugins/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index a14761b..69e29c6 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -29,8 +29,27 @@ type mapEntry struct { const todo = "TODO(new-plugin)" +// legacyFormats are the old --format names, each the template it is now. +var legacyFormats = map[string]string{ + "feed": "notices/feed", + "retirements": "notices/deprecations", + "migrationguide": "migrationguide/sdk", + "removedmembers": "migrationguide/members", + "changelog": "changelog/markdown", + "apichangelog": "changelog/json", + "catalog": "catalog", + "openapi": "openapi", +} + +// defaultReaders are the reader --kind picks when --reader is left out. +var defaultReaders = map[string]string{ + "notices": "deprecations", + "migrationguide": "sdk", + "changelog": "markdown", +} + var formats = map[string]formatSpec{ - "feed": { + "notices/feed": { kind: "notices", layer: "api", defDir: "plugins/notices/feed", @@ -81,7 +100,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed"}, }, - "retirements": { + "notices/deprecations": { kind: "notices", layer: "ai-models", defDir: "plugins/notices/retire", @@ -155,7 +174,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire"}, }, - "migrationguide": { + "migrationguide/sdk": { kind: "migrationguide", layer: "sdk", defDir: "plugins/migrationguide/sdkguide", @@ -222,7 +241,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide"}, }, - "removedmembers": { + "migrationguide/members": { kind: "migrationguide", layer: "package", defDir: "plugins/migrationguide/members", @@ -298,7 +317,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members"}, }, - "changelog": { + "changelog/markdown": { kind: "changelog", layer: "package", defDir: "plugins/changelog", @@ -340,7 +359,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, }, - "apichangelog": { + "changelog/json": { kind: "changelog", layer: "api", defDir: "plugins/changelog", @@ -437,6 +456,8 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { import ( "context" "fmt" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // {{.Ident}} adapts {{.Provider}}'s OpenAPI spec for the openapi plugin. @@ -460,6 +481,14 @@ func ({{.Ident}}) LatestTag(ctx context.Context) (string, error) { func ({{.Ident}}) Fetch(ctx context.Context, tag string) (Spec, error) { return Spec{}, fmt.Errorf("{{.ID}}: Fetch isn't written yet (plugins/openapi/adapter/{{.File}}.go)") } + +// Versions are every release of the spec, oldest first, each with the Ref +// Fetch takes: what lets every pair of releases be diffed, not only the +// newest. ` + todo + `: list them with core/versions (GitHubReleases, +// GitHubCommits, GitHubTags), as versions.go does for the other adapters. +func ({{.Ident}}) Versions(ctx context.Context) ([]plugin.Version, error) { + return nil, fmt.Errorf("{{.ID}}: Versions isn't written yet (plugins/openapi/adapter/{{.File}}.go)") +} `, register: `plugin.Register(Plugin{Adapter: adapter.{{.Ident}}{}})`, pluginOf: `Plugin{Adapter: adapter.{{.Ident}}{}}`, @@ -501,7 +530,89 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { } `, imports: []string{"context", "fmt", "os", "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter", "github.com/patch-it-dev/patch-it-plugins/core/event"}, - next: "Write LatestTag and Fetch in plugins/openapi/adapter/{{.File}}.go (fetch.Get only); add Diff/Keep to the Register line if the spec needs them (see vercel.go).", + next: "Write LatestTag, Fetch and Versions in plugins/openapi/adapter/{{.File}}.go (fetch.Get only); add Diff/Keep to the Register line if the spec needs them (see vercel.go).", + }, + "apisurface": { + kind: "apisurface", + layer: "sdk", + defDir: "plugins/apisurface", + def: `package apisurface + +// {{.Ident}} is {{.Provider}}'s package on PyPI, its public API read from each +// release's wheel. +// +// ` + todo + `: check the name on PyPI and the top-level module code +// imports (from --package, or guessed). Say +// what you checked, with the date: that the wheel holds the package's .py +// (or .pyi) files. +var {{.Ident}} = Package{Name: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Module}}"} +`, + register: `plugin.Register(Plugin{Package: {{.Ident}}})`, + pluginOf: `Plugin{Package: {{.Ident}}}`, + fixtures: map[string]string{ + "{{.File}}-old.py": "# ` + todo + `: a placeholder for the older release's module. Save the real release's wheel instead (see apisurface_test.go).\ndef placeholder(a, b=1):\n pass\n", + "{{.File}}-new.py": "# ` + todo + `: a placeholder for the newer release's module: it drops b, one event.\ndef placeholder(a):\n pass\n", + }, + // The drop test's newer release: the older one again, nothing gone. + dropFile: "# ` + todo + `: a placeholder: a release that only adds or changes private names.\ndef placeholder(a, b=1):\n pass\n\ndef _private(x):\n pass\n", + source: "{{.File}}-new.py", + ingest: `// {{.Lower}}Ingest compares two releases: 1.0.0, a wheel holding +// testdata/{{.File}}-old.py as {{.Module}}/__init__.py, and 1.1.0, one +// holding file. The wheels are built here so the placeholders are text. +// ` + todo + `: save the two real wheels (trimmed if they're large, as +// apisurface_test.go's are) and serve them instead. +func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { + t.Helper() + wheel := func(src string) []byte { + var buf bytes.Buffer + zw := zip.NewWriter(&buf) + w, err := zw.Create("{{.Module}}/__init__.py") + if err != nil { + t.Fatal(err) + } + w.Write(kittest.Read(t, src)) + if err := zw.Close(); err != nil { + t.Fatal(err) + } + return buf.Bytes() + } + files := map[string][]byte{ + "https://pypi.org/pypi/{{.PyPI}}/json": []byte(` + "`" + `{"releases": {"1.0.0": [{"upload_time_iso_8601": "2026-01-01T00:00:00Z"}], "1.1.0": [{"upload_time_iso_8601": "2026-02-01T00:00:00Z"}]}}` + "`" + `), + "https://pypi.org/pypi/{{.PyPI}}/1.0.0/json": []byte(` + "`" + `{"urls": [{"packagetype": "bdist_wheel", "filename": "{{.Module}}-1.0.0-py3-none-any.whl", "url": "https://example.com/{{.Module}}-1.0.0-py3-none-any.whl"}]}` + "`" + `), + "https://pypi.org/pypi/{{.PyPI}}/1.1.0/json": []byte(` + "`" + `{"urls": [{"packagetype": "bdist_wheel", "filename": "{{.Module}}-1.1.0-py3-none-any.whl", "url": "https://example.com/{{.Module}}-1.1.0-py3-none-any.whl"}]}` + "`" + `), + "https://example.com/{{.Module}}-1.0.0-py3-none-any.whl": wheel("testdata/{{.File}}-old.py"), + "https://example.com/{{.Module}}-1.1.0-py3-none-any.whl": wheel(file), + } + env := kittest.Env(t, nil) + env.Get = func(_ context.Context, url string) ([]byte, error) { + if b, ok := files[url]; ok { + return b, nil + } + t.Errorf("fetched %s, which the test didn't save", url) + return nil, fmt.Errorf("no saved copy of %s", url) + } + ctx, p := context.Background(), Plugin{Package: {{.Ident}}} + vs, err := p.ListVersions(ctx, env) + if err != nil || len(vs) != 2 { + t.Fatalf("versions %v: %v", vs, err) + } + from, err := p.ReadAt(ctx, env, vs[0]) + if err != nil { + t.Fatal(err) + } + to, err := p.ReadAt(ctx, env, vs[1]) + if err != nil { + t.Fatal(err) + } + res, err := p.Extract(ctx, env, from, to) + if err != nil || len(res.Rejected) > 0 { + t.Fatalf("%v %v", err, res.Rejected) + } + return res.Events +} +`, + imports: []string{"archive/zip", "bytes", "context", "fmt", "github.com/patch-it-dev/patch-it-plugins/core/event"}, + next: "Save two real wheels of the package and serve them in {{.Lower}}Ingest; the kind reads their .py files, never runs them.", }, } diff --git a/cmd/new-plugin/main.go b/cmd/new-plugin/main.go index 7fc2db6..bc2b712 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -1,23 +1,36 @@ -// Command new-plugin scaffolds a provider on one of the format plugins, so a -// contributor only fills in what is specific to the provider. Run it from the -// repo root: +// Command new-plugin scaffolds a source of a provider on one of the kinds, +// so a contributor only fills in what is specific to it. Run it from the +// repo root (or `make new-plugin ARGS='...'`): // -// go run ./cmd/new-plugin --api acme --provider Acme --format openapi +// go run ./cmd/new-plugin --provider acme --name Acme --category devtools \ +// --homepage https://acme.example --source api --kind openapi \ +// --url https://github.com/acme/openapi --package pypi:acme // -// It writes the provider's definition in the format's package (or the reader -// package the format uses: plugins/openapi/adapter/, plugins/retirements/retire/, -// plugins/migrationguide/sdkguide/), adds its -// plugin.RegisterProvider block (the source's metadata) to plugins/'s -// init, a test (registered, golden, drop) over placeholder sources with an -// empty golden file, a row in that testdata/README.md, and providers/.md -// from providers/_template.md. `go test ./...` -// passes right after; every place to fill in says TODO(new-plugin). +// A flag left out is asked for when the command runs in a terminal; a +// second source of a registered provider needs only --provider, --source +// and --kind (the provider's name, category and homepage come from the +// registry). Run it once per source. // -// It changes nothing when the id is taken (registered, or a file it would -// write exists). +// It writes the source's definition in the kind's package (or the reader +// package the kind uses: plugins/openapi/adapter/, plugins/notices/retire/, +// plugins/notices/feed/, plugins/migrationguide/sdkguide/, +// plugins/migrationguide/members/), with the version wiring the kind needs +// from it (an OpenAPI adapter's Versions; every other kind lists, reads and +// extracts versions itself), adds the plugin.RegisterProvider block (the +// provider and the source with their metadata) to the kind's init, a test +// (registered, golden, drop) over placeholder sources with an empty golden +// file, a row in that testdata/README.md, providers/.md from +// providers/_template.md, and the kind's import in plugins/all when it isn't +// there. `go test ./...` passes right after; every place to fill in says +// TODO(new-plugin). +// +// It changes nothing when the provider/source id or the first name is +// taken, or a file it would write exists. The old flags (--api, --provider +// as the name, --format, --source as the URL) still work for one release. package main import ( + "bufio" "bytes" "flag" "fmt" @@ -42,31 +55,75 @@ import ( // Options are the command's flags. type Options struct { - Root string // the repo root - API string // the plugin id: --api and every event's api - Provider string // whose API, SDK or package - Format string // the format plugin - Layer string // the source's layer (plugin.Layers()); "" is the format's default - Source string // the provider's source URL; "" is a placeholder - Watches string // what the source watches, in a few words - Page string // the provider page, providers/.md; "" is the id. An existing page is shared, not rewritten - Today time.Time + Root string // the repo root + + // The provider. + ProviderID string // lowercase slug: "acme" + Provider string // its name, as it writes it: "Acme" + Category string // one of plugin.Categories(); a registered provider's is kept + Homepage string // its own site + + // The source. + SourceID string // unique within the provider: "api", "python-sdk" + Kind string // the kind that reads it: plugins/ + Reader string // for a kind with several readers: "feed" for notices; "" is the kind's default + Layer string // the source's layer (plugin.Layers()); "" is the template's default + URLs []string // the provider's pages or files it reads; none is a placeholder + Packages []string // the packages it covers, "pypi:acme" + Watches string // what the source watches, in a few words + Page string // the provider page, providers/.md; "" is the first name. An existing page is shared, not rewritten + API string // its first name, the old slug events carry in api; "" is - (or the provider's id when they're the same) + + // Deprecated: Format is a template ("openapi", "notices/feed") or an old + // format name ("feed"); Kind and Reader replace it. Source is the first + // URL (URLs replaces it). + Format string + Source string + + Today time.Time // Go runs the go command afterwards: the golden file from the placeholders // (go test -update). Go bool } +// list is a repeatable flag. +type list []string + +func (l *list) String() string { return strings.Join(*l, ",") } +func (l *list) Set(v string) error { *l = append(*l, v); return nil } + func main() { var o Options + var urls, packages list + var provider, source string flag.StringVar(&o.Root, "root", ".", "the repo root") - flag.StringVar(&o.API, "api", "", "the plugin id, e.g. acme or acme-models (lowercase letters, digits, hyphens)") - flag.StringVar(&o.Provider, "provider", "", "the provider's name, e.g. Acme") - flag.StringVar(&o.Format, "format", "", "the format plugin: "+strings.Join(formatNames(), ", ")) - flag.StringVar(&o.Layer, "layer", "", "the source's layer: api, sdk, package, runtime, ci, ai-models or infra (default: the format's)") - flag.StringVar(&o.Source, "source", "", "the provider's source URL (default: a placeholder to fill in)") + flag.StringVar(&provider, "provider", "", "the provider's id, e.g. acme (with --format: its name, the old meaning)") + flag.StringVar(&o.Provider, "name", "", "the provider's name as it writes it, e.g. Acme (a registered provider's is kept)") + flag.StringVar(&o.Category, "category", "", "the provider's category: "+strings.Join(categories(), ", ")) + flag.StringVar(&o.Homepage, "homepage", "", "the provider's own site, https://...") + flag.StringVar(&source, "source", "", "the source's id within the provider, e.g. api or python-sdk (with --format: its URL, the old meaning)") + flag.StringVar(&o.Kind, "kind", "", "the kind that reads it: "+strings.Join(kindNames(), ", ")) + flag.StringVar(&o.Reader, "reader", "", "the kind's reader, for a kind with several: "+readerHelp()) + flag.StringVar(&o.Layer, "layer", "", "the source's layer: api, sdk, package, runtime, ci, ai-models or infra (default: the kind's)") + flag.Var(&urls, "url", "a page or file the source reads, https://... (repeatable; default: a placeholder to fill in)") + flag.Var(&packages, "package", "a package the source covers, ecosystem:name, e.g. pypi:acme or npm:@acme/sdk (repeatable)") flag.StringVar(&o.Watches, "watches", "", "what it watches, in a few words (default: a placeholder)") - flag.StringVar(&o.Page, "page", "", "the provider page, providers/.md (default: the --api id); one page per provider, so a second plugin of a provider names the existing page") + flag.StringVar(&o.Page, "page", "", "the provider page, providers/.md (default: the first name); a second source of a provider may share the existing page") + flag.StringVar(&o.API, "api", "", "the source's first name, the slug events carry in api (default: -)") + flag.StringVar(&o.Format, "format", "", "deprecated, for one release: the old format names ("+strings.Join(legacyNames(), ", ")+"), with --api, --provider and --source ") flag.Parse() + o.URLs, o.Packages = urls, packages + if o.Format != "" { + o.Provider, o.Source = provider, source + } else { + o.ProviderID, o.SourceID = provider, source + if term() { + if err := ask(&o, bufio.NewReader(os.Stdin), os.Stdout); err != nil { + fmt.Fprintln(os.Stderr, "new-plugin:", err) + os.Exit(1) + } + } + } o.Today = time.Now().UTC() o.Go = true if err := Run(o, os.Stdout); err != nil { @@ -75,6 +132,7 @@ func main() { } } +// formatNames are the templates: a kind, or kind/reader. func formatNames() []string { var names []string for n := range formats { @@ -84,6 +142,77 @@ func formatNames() []string { return names } +// kindNames are the kinds a template scaffolds. +func kindNames() []string { + var names []string + for n := range formats { + k, _, _ := strings.Cut(n, "/") + if !slices.Contains(names, k) { + names = append(names, k) + } + } + slices.Sort(names) + return names +} + +func readerHelp() string { + var parts []string + for _, k := range kindNames() { + var rs []string + for _, n := range formatNames() { + if kind, r, ok := strings.Cut(n, "/"); ok && kind == k { + rs = append(rs, r) + } + } + if len(rs) > 0 { + parts = append(parts, k+": "+strings.Join(rs, "|")+" (default "+defaultReaders[k]+")") + } + } + return strings.Join(parts, "; ") +} + +func legacyNames() []string { + var names []string + for n := range legacyFormats { + names = append(names, n) + } + slices.Sort(names) + return names +} + +func categories() []string { + var out []string + for _, c := range plugin.Categories() { + out = append(out, string(c)) + } + return out +} + +// template is the template o asks for: from --kind and --reader, or the +// deprecated --format. +func (o Options) template() (string, error) { + if o.Format != "" { + if t, ok := legacyFormats[o.Format]; ok { + return t, nil + } + if _, ok := formats[o.Format]; ok { + return o.Format, nil + } + return "", fmt.Errorf("--format %q: want one of %s", o.Format, strings.Join(legacyNames(), ", ")) + } + if !slices.Contains(kindNames(), o.Kind) { + return "", fmt.Errorf("--kind %q: want one of %s", o.Kind, strings.Join(kindNames(), ", ")) + } + if _, ok := formats[o.Kind]; ok && o.Reader == "" { + return o.Kind, nil + } + r := cmp(o.Reader, defaultReaders[o.Kind]) + if _, ok := formats[o.Kind+"/"+r]; !ok { + return "", fmt.Errorf("--reader %q: kind %s's readers are %s", o.Reader, o.Kind, readerHelp()) + } + return o.Kind + "/" + r, nil +} + var ( validID = regexp.MustCompile(`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`) validURL = regexp.MustCompile(`^https://[^\s|()]+$`) @@ -94,17 +223,22 @@ var ( // data is what the templates fill in. type data struct { - ID, Ident, Lower, Provider, Source, File, Format, Kind string - Slug string // the provider, lowercase: a model subject's provider - SourceFile, DropFile, PluginOf, Ingest, Drop string - Imports []string + ID, Ident, Lower, Provider, Source, File, Format, Kind, Module, PyPI string + Slug string // the provider, lowercase: a model subject's provider + SourceFile, DropFile, PluginOf, Ingest, Drop string + Imports []string } -// Run scaffolds the plugin, or changes nothing and says why. +// Run scaffolds the source, or changes nothing and says why. func Run(o Options, out io.Writer) error { - f, ok := formats[o.Format] - if !ok { - return fmt.Errorf("--format %q: want one of %s", o.Format, strings.Join(formatNames(), ", ")) + tmpl, err := o.template() + if err != nil { + return err + } + o.Format = tmpl + f := formats[tmpl] + if err := o.resolve(); err != nil { + return err } if !validID.MatchString(o.API) || o.API == "all" { return fmt.Errorf("--api %q: want lowercase letters, digits and single hyphens, starting with a letter (acme, acme-models), and not \"all\"", o.API) @@ -118,10 +252,28 @@ func Run(o Options, out io.Writer) error { if !slices.Contains(plugin.Layers(), plugin.Layer(o.Layer)) { return fmt.Errorf("--layer %q: want one of %v", o.Layer, plugin.Layers()) } + if o.Source == "" && len(o.URLs) > 0 { + o.Source = o.URLs[0] + } if o.Source == "" { o.Source = "https://example.com/TODO-" + o.API + "-source" - } else if !validURL.MatchString(o.Source) { - return fmt.Errorf("--source %q: want an https URL", o.Source) + } + if len(o.URLs) == 0 { + o.URLs = []string{o.Source} + } + for _, u := range o.URLs { + if !validURL.MatchString(u) { + return fmt.Errorf("--url %q: want an https URL", u) + } + } + if len(o.Packages) == 0 && f.kind == "apisurface" { + o.Packages = []string{"pypi:" + o.ProviderID} + } + for _, p := range o.Packages { + eco, name, ok := strings.Cut(p, ":") + if !ok || !slices.Contains(plugin.Ecosystems(), eco) || name == "" || !cellSafe.MatchString(name) || strings.ContainsAny(name, " \t") { + return fmt.Errorf("--package %q: want ecosystem:name, the ecosystem one of %v", p, plugin.Ecosystems()) + } } if o.Watches == "" { o.Watches = "TODO: what it watches, in a few words" @@ -140,10 +292,20 @@ func Run(o Options, out io.Writer) error { // Taken? Check everything before writing anything. if _, ok := plugin.Lookup(o.API); ok { - return fmt.Errorf("a plugin named %q is already registered: pick another --api", o.API) + return fmt.Errorf("a source named %q is already registered: pick another --api (the first name)", o.API) + } + if _, ok := plugin.LookupSource(o.ProviderID + "/" + o.SourceID); ok { + return fmt.Errorf("source %s/%s is already registered: pick another --source", o.ProviderID, o.SourceID) } - d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format, Kind: f.kind} + d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format, Kind: f.kind, PyPI: o.API} + for _, p := range o.Packages { + if name, ok := strings.CutPrefix(p, "pypi:"); ok { + d.PyPI = name + break + } + } + d.Module = strings.ReplaceAll(strings.ToLower(d.PyPI), "-", "_") d.Ident = ident(o.API) d.Lower = string(unicode.ToLower(rune(d.Ident[0]))) + d.Ident[1:] d.File = fileBase(o.API) @@ -207,6 +369,11 @@ func Run(o Options, out io.Writer) error { return err } edits := map[string][]byte{mainFile: registered} + if all, ok, err := importInAll(o.Root, f.kind); err != nil { + return err + } else if ok { + edits[filepath.Join("plugins", "all", "all.go")] = all + } if m := f.mapEntry; m != nil { if edits[m.file], err = addMapEntry(filepath.Join(o.Root, m.file), m.varName, fill(m.entry, d)); err != nil { return err @@ -240,7 +407,7 @@ func Run(o Options, out io.Writer) error { paths = append(paths, path) } slices.Sort(paths) - fmt.Fprintf(out, "Scaffolded %s (%s, format %s):\n", o.API, o.Provider, o.Format) + fmt.Fprintf(out, "Scaffolded %s/%s (%s, first name %s, kind %s):\n", o.ProviderID, o.SourceID, o.Provider, o.API, o.Format) for _, p := range paths { fmt.Fprintln(out, " "+p) } @@ -360,30 +527,42 @@ func declNames(decl ast.Decl) []string { return nil } -// providerBlock turns a format's "plugin.Register()" line into the -// provider's registration with its metadata: a provider already registered -// (a second source of Algolia) keeps its id, category and homepage; a new one -// gets placeholders that say TODO(new-plugin). +// providerBlock turns a template's "plugin.Register()" line into +// the provider's registration with its metadata: a provider already +// registered (a second source of Algolia) keeps its name, category and +// homepage; a new one gets what the flags say, or placeholders that say +// TODO(new-plugin). func providerBlock(o Options, d data, line string) string { expr := strings.TrimSuffix(strings.TrimPrefix(line, "plugin.Register("), ")") - id, category, homepage := d.Slug, "plugin.CategoryDevTools, // TODO(new-plugin): the provider's category, one of plugin.Categories()\n\t\t", `"https://example.com/TODO-`+d.Slug+`-homepage", // TODO(new-plugin): the provider's own site`+"\n\t\t" - for _, p := range plugin.Providers() { - if strings.EqualFold(p.Name, o.Provider) { - id, category, homepage = p.ID, fmt.Sprintf("%q,", p.Category), fmt.Sprintf("%q,", p.Homepage) - category = "plugin.Category(" + strings.TrimSuffix(category, ",") + ")," - } + category := "plugin.CategoryDevTools, // TODO(new-plugin): the provider's category, one of plugin.Categories()\n\t\t" + if o.Category != "" { + category = fmt.Sprintf("plugin.Category(%q),", o.Category) + } + homepage := `"https://example.com/TODO-` + o.ProviderID + `-homepage", // TODO(new-plugin): the provider's own site` + "\n\t\t" + if o.Homepage != "" { + homepage = fmt.Sprintf("%q,", o.Homepage) + } + var urls, pkgs []string + for _, u := range o.URLs { + urls = append(urls, fmt.Sprintf("%q", u)) + } + for _, p := range o.Packages { + pkgs = append(pkgs, fmt.Sprintf("%q", p)) + } + packages := "" + if len(pkgs) > 0 { + packages = fmt.Sprintf("\n\t\t\tPackages: []string{%s},", strings.Join(pkgs, ", ")) } - source := strings.TrimPrefix(o.API, id+"-") return fmt.Sprintf(`plugin.RegisterProvider(plugin.Provider{ ID: %q, Name: %q, Category: %s Homepage: %s Sources: []plugin.Source{{ ID: %q, Layer: %q, Page: %q, Watches: %q, - URLs: []string{%q}, + URLs: []string{%s},%s Plugin: %s, }}, - })`, id, o.Provider, category, homepage, source, o.Layer, "providers/"+o.Page+".md", o.Watches, o.Source, expr) + })`, o.ProviderID, o.Provider, category, homepage, o.SourceID, o.Layer, "providers/"+o.Page+".md", o.Watches, strings.Join(urls, ", "), packages, expr) } // register adds line at the end of the init func that registers pkgDir's diff --git a/cmd/new-plugin/main_test.go b/cmd/new-plugin/main_test.go index 3092ef5..087e8f6 100644 --- a/cmd/new-plugin/main_test.go +++ b/cmd/new-plugin/main_test.go @@ -1,6 +1,7 @@ package main import ( + "bufio" "bytes" "crypto/sha256" "io" @@ -16,10 +17,18 @@ import ( var today = time.Date(2026, 11, 19, 0, 0, 0, 0, time.UTC) -// A plugin of every format, scaffolded into a copy of the repo: the copy -// builds, vets and passes its tests, and list-plugins lists them all. -// Then the same command again changes nothing. -func TestScaffoldEveryFormat(t *testing.T) { +// optionsFor is a source of the provider acme on template tmpl ("openapi", +// "notices/feed"). +func optionsFor(root, tmpl string) Options { + kind, reader, _ := strings.Cut(tmpl, "/") + return Options{Root: root, ProviderID: "acme", Provider: "Acme Corp", SourceID: strings.ReplaceAll(tmpl, "/", "-"), + Kind: kind, Reader: reader, Packages: []string{"pypi:acme-" + strings.ReplaceAll(tmpl, "/", "-")}, Today: today, Go: true} +} + +// A source of every kind and reader, scaffolded into a copy of the repo: +// the copy builds, vets and passes its tests, and list-plugins lists them +// all. Then the same command again changes nothing. +func TestScaffoldEveryKind(t *testing.T) { if testing.Short() { t.Skip("runs the go command over a copy of the repo") } @@ -29,7 +38,7 @@ func TestScaffoldEveryFormat(t *testing.T) { } root := copyRepo(t) for _, f := range formatNames() { - o := Options{Root: root, API: "acme-" + f, Provider: "Acme Corp", Format: f, Today: today, Go: true} + o := optionsFor(root, f) var out bytes.Buffer if err := Run(o, &out); err != nil { t.Fatalf("%s: %v\n%s", f, err, out.String()) @@ -52,13 +61,14 @@ func TestScaffoldEveryFormat(t *testing.T) { t.Fatalf("go run ./cmd/list-plugins: %v", err) } for _, f := range formatNames() { - if !bytes.Contains(listed, []byte(`"alias": "acme-`+f+`"`)) { - t.Errorf("list-plugins doesn't list acme-%s", f) + id := strings.ReplaceAll(f, "/", "-") + if !bytes.Contains(listed, []byte(`"id": "acme/`+id+`"`)) || !bytes.Contains(listed, []byte(`"pypi:acme-`+id+`"`)) { + t.Errorf("list-plugins doesn't list acme/%s with its package", id) } } before := tree(t, root) - err = Run(Options{Root: root, API: "acme-feed", Provider: "Acme Corp", Format: "feed", Today: today, Go: true}, io.Discard) + err = Run(optionsFor(root, "notices/feed"), io.Discard) if err == nil || !strings.Contains(err.Error(), "already exists") { t.Errorf("second run: err = %v, want the id taken", err) } @@ -90,16 +100,24 @@ func TestRefusesBadInput(t *testing.T) { root := copyRepo(t) before := tree(t, root) for name, o := range map[string]Options{ - "unknown format": {API: "acme", Provider: "Acme", Format: "graphql"}, - "uppercase id": {API: "Acme", Provider: "Acme", Format: "feed"}, - "double hyphen": {API: "acme--x", Provider: "Acme", Format: "feed"}, - "id all": {API: "all", Provider: "Acme", Format: "feed"}, - "registered id": {API: "stripe", Provider: "Stripe", Format: "openapi"}, - "no provider": {API: "acme", Format: "feed"}, - "pipe in name": {API: "acme", Provider: "Ac|me", Format: "feed"}, - "unknown layer": {API: "acme", Provider: "Acme", Format: "feed", Layer: "database"}, - "http source": {API: "acme", Provider: "Acme", Format: "feed", Source: "http://acme.example/feed"}, - "provider exists": {API: "numpy", Provider: "NumPy", Format: "changelog"}, + "unknown kind": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "graphql"}, + "unknown reader": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "notices", Reader: "tweets"}, + "no source id": {ProviderID: "acme", Provider: "Acme", Kind: "openapi"}, + "source registered": {ProviderID: "stripe", SourceID: "api", Kind: "openapi"}, + "other name": {ProviderID: "stripe", Provider: "Stripe Inc", SourceID: "sdk", Kind: "apisurface"}, + "bad category": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", Category: "toys"}, + "bad package": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", Packages: []string{"pip:acme"}}, + "first name taken": {ProviderID: "acme", Provider: "Acme", SourceID: "api", Kind: "openapi", API: "stripe"}, + "unknown format": {API: "acme", Provider: "Acme", Format: "graphql"}, + "uppercase id": {API: "Acme", Provider: "Acme", Format: "feed"}, + "double hyphen": {API: "acme--x", Provider: "Acme", Format: "feed"}, + "id all": {API: "all", Provider: "Acme", Format: "feed"}, + "registered id": {API: "stripe", Provider: "Stripe", Format: "openapi"}, + "no provider": {API: "acme", Format: "feed"}, + "pipe in name": {API: "acme", Provider: "Ac|me", Format: "feed"}, + "unknown layer": {API: "acme", Provider: "Acme", Format: "feed", Layer: "database"}, + "http source": {API: "acme", Provider: "Acme", Format: "feed", Source: "http://acme.example/feed"}, + "provider exists": {API: "numpy", Provider: "NumPy", Format: "changelog"}, } { o.Root, o.Today = root, today if err := Run(o, io.Discard); err == nil { @@ -187,3 +205,20 @@ func hash(b []byte) string { sum := sha256.Sum256(b) return string(sum[:]) } + +// Asked at a terminal: what the flags left out, a registered provider's +// name, category and homepage not asked again. +func TestAsksWhatIsMissing(t *testing.T) { + o := Options{ProviderID: "stripe"} + in := bufio.NewReader(strings.NewReader("python-sdk\napisurface\nsdk\nhttps://pypi.org/project/stripe/\npypi:stripe\nRemoved names\n")) + var out bytes.Buffer + if err := ask(&o, in, &out); err != nil { + t.Fatal(err) + } + if o.SourceID != "python-sdk" || o.Kind != "apisurface" || o.Layer != "sdk" || o.URLs[0] != "https://pypi.org/project/stripe/" || o.Packages[0] != "pypi:stripe" || o.Watches != "Removed names" || o.Provider != "" { + t.Errorf("%+v", o) + } + if strings.Contains(out.String(), "Provider name") { + t.Errorf("asked for a registered provider's name:\n%s", out.String()) + } +} diff --git a/cmd/new-plugin/resolve.go b/cmd/new-plugin/resolve.go new file mode 100644 index 0000000..7b3ab38 --- /dev/null +++ b/cmd/new-plugin/resolve.go @@ -0,0 +1,170 @@ +package main + +import ( + "bufio" + "bytes" + "fmt" + "go/format" + "io" + "os" + "path/filepath" + "regexp" + "slices" + "strings" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +// resolve fills in the provider and source from the registry and the +// flags: a registered provider's name, category and homepage, the first +// name, and, for the deprecated flags, the ids from the name and --api. +func (o *Options) resolve() error { + if o.ProviderID == "" && o.Provider != "" { // the old flags: --provider is the name + o.ProviderID = strings.Trim(regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(strings.ToLower(o.Provider), "-"), "-") + for _, p := range plugin.Providers() { + if strings.EqualFold(p.Name, o.Provider) { + o.ProviderID = p.ID + } + } + if o.SourceID == "" { + o.SourceID = strings.TrimPrefix(o.API, o.ProviderID+"-") + } + } + if !validID.MatchString(o.ProviderID) { + return fmt.Errorf("--provider %q: want the provider's id, lowercase letters, digits and single hyphens (acme)", o.ProviderID) + } + if !validID.MatchString(o.SourceID) { + return fmt.Errorf("--source %q: want the source's id within the provider, lowercase letters, digits and single hyphens (api, python-sdk)", o.SourceID) + } + if i := slices.IndexFunc(plugin.Providers(), func(p plugin.Provider) bool { return p.ID == o.ProviderID }); i >= 0 { + p := plugin.Providers()[i] + switch { + case o.Provider != "" && !strings.EqualFold(o.Provider, p.Name): + return fmt.Errorf("--name %q: provider %s is registered as %q", o.Provider, p.ID, p.Name) + case o.Category != "" && o.Category != string(p.Category): + return fmt.Errorf("--category %q: provider %s is registered in %q", o.Category, p.ID, p.Category) + case o.Homepage != "" && o.Homepage != p.Homepage: + return fmt.Errorf("--homepage %q: provider %s is registered with %q", o.Homepage, p.ID, p.Homepage) + } + o.Provider, o.Category, o.Homepage = p.Name, string(p.Category), p.Homepage + } else { + if o.Category != "" && !slices.Contains(categories(), o.Category) { + return fmt.Errorf("--category %q: want one of %s", o.Category, strings.Join(categories(), ", ")) + } + if o.Homepage != "" && !validURL.MatchString(o.Homepage) { + return fmt.Errorf("--homepage %q: want an https URL", o.Homepage) + } + } + if o.API == "" { + o.API = o.ProviderID + "-" + o.SourceID + if o.SourceID == o.ProviderID { + o.API = o.ProviderID + } + } + return nil +} + +// term is true when stdin is a terminal: flags left out are asked for. +func term() bool { + fi, err := os.Stdin.Stat() + return err == nil && fi.Mode()&os.ModeCharDevice != 0 +} + +// ask fills in, from a person at a terminal, what the flags left out: only +// when one of the provider id, the source id or the kind is missing (a full +// command line asks nothing). +func ask(o *Options, in *bufio.Reader, out io.Writer) error { + if o.ProviderID != "" && o.SourceID != "" && o.Kind != "" { + return nil + } + prompt := func(field *string, question, def string) error { + if *field != "" { + return nil + } + if def != "" { + question += " [" + def + "]" + } + fmt.Fprint(out, question+": ") + line, _ := in.ReadString('\n') // no answer (end of input) is the default + *field = cmp(strings.TrimSpace(line), def) + return nil + } + list := func(field *[]string, question string) error { + if len(*field) > 0 { + return nil + } + var answer string + if err := prompt(&answer, question+" (comma-separated, empty for none)", ""); err != nil { + return err + } + for _, v := range strings.Split(answer, ",") { + if v = strings.TrimSpace(v); v != "" { + *field = append(*field, v) + } + } + return nil + } + if err := prompt(&o.ProviderID, "Provider id (acme)", ""); err != nil { + return err + } + if !slices.ContainsFunc(plugin.Providers(), func(p plugin.Provider) bool { return p.ID == o.ProviderID }) { + for _, q := range []struct { + field *string + question string + }{ + {&o.Provider, "Provider name, as it writes it (Acme)"}, + {&o.Category, "Category (" + strings.Join(categories(), ", ") + ")"}, + {&o.Homepage, "Homepage (https://...)"}, + } { + if err := prompt(q.field, q.question, ""); err != nil { + return err + } + } + } + if err := prompt(&o.SourceID, "Source id within the provider (api, python-sdk)", ""); err != nil { + return err + } + if err := prompt(&o.Kind, "Kind ("+strings.Join(kindNames(), ", ")+"; docs/which-kind.md)", ""); err != nil { + return err + } + if def := defaultReaders[o.Kind]; def != "" { + if err := prompt(&o.Reader, "Reader ("+readerHelp()+")", def); err != nil { + return err + } + } + if err := prompt(&o.Layer, "Layer (api, sdk, package, runtime, ci, ai-models, infra; empty for the kind's default)", ""); err != nil { + return err + } + if err := list(&o.URLs, "URLs it reads (https://...)"); err != nil { + return err + } + if err := list(&o.Packages, "Packages it covers (pypi:acme, npm:@acme/sdk)"); err != nil { + return err + } + return prompt(&o.Watches, "What it watches, in a few words", "") +} + +func cmp(a, b string) string { + if a != "" { + return a + } + return b +} + +// importInAll adds plugins/ to plugins/all's imports when it isn't +// there (a new kind), so a program importing all runs it. ok is false when +// it's already there. +func importInAll(root, kind string) ([]byte, bool, error) { + path := filepath.Join(root, "plugins", "all", "all.go") + src, err := os.ReadFile(path) + if err != nil { + return nil, false, err + } + imp := `"github.com/patch-it-dev/patch-it-plugins/plugins/` + kind + `"` + if bytes.Contains(src, []byte(imp)) { + return nil, false, nil + } + out := bytes.Replace(src, []byte("import (\n"), []byte("import (\n\t_ "+imp+"\n"), 1) + b, err := format.Source(out) + return b, err == nil, err +} diff --git a/docs/which-kind.md b/docs/which-kind.md new file mode 100644 index 0000000..59374d3 --- /dev/null +++ b/docs/which-kind.md @@ -0,0 +1,24 @@ +# Which kind fits my provider? + +A provider has one or more sources: each place it publishes changes. Each source is read by one **kind**. Answer the questions below for one source, top to bottom; the first "yes" is its kind. A provider with several sources (an API spec and an SDK, say) asks them once per source. + +The list of what's already covered isn't here: `make plugins` prints it from the code. + +| Ask | If yes, the kind | It reads | Examples of the shape | +|---|---|---|---| +| Does the provider publish an **OpenAPI spec** of its API, per release or per commit? | `openapi` | Two specs, diffed: removed and renamed operations, parameters, fields; deprecations | A spec repo with release tags; a spec file a repo commits on every change | +| Is there a **guide that lists what a release removed**, one per major or per release, in a table? | `migrationguide` | The guide at the release's tag: removed request parameters (reader `sdk`) or removed members of a module (reader `members`, RST or Markdown tables) | `MIGRATION.md` per major; "removed members" tables in a 2.0 migration guide; an API version removal guide | +| Is there a **changelog**: a file per release (`CHANGELOG.md`, `CHANGES.rst`, `HISTORY.rst`), or a machine-readable JSON changelog? | `changelog` | The release's section at its tag (reader `markdown`), or the life-cycle entries a JSON changelog adds commit by commit (reader `json`) | Keep a Changelog files; reStructuredText release notes; an API changelog JSON in a repo; a Terraform provider's changelog | +| Is there a **live page of dated notices**: a deprecations or shutdown table, an end-of-life table, or an **RSS/Atom feed** of announcements? | `notices` | The page as it is now, cited through a Web Archive snapshot; its past versions are its Web Archive captures (reader `deprecations`, `feed`, or an end-of-life table) | A model deprecations page; an API end-of-life policy table; a changelog feed with a "deprecation" label; a Kubernetes API removals page | +| Is there a **flat catalog**, one JSON entry per name (a command, an endpoint), with no release tags? | `catalog` | Two snapshots, compared for names that disappeared entirely | A list of commands a server accepts, kept in a repo | +| Is it a **published package** with no changelog worth reading? | `apisurface` | Each release's files from the registry (PyPI first), compared: removed or renamed classes, functions, methods, and parameters removed or newly required | An SDK generated from a spec, released often, whose changelog says "chore: update types" | + +Still no "yes"? Open a [discussion](https://github.com/patch-it-dev/patch-it-plugins/discussions) with the source's link: a new kind is a new package under `plugins/`, and the questions above get one more row. + +## Two sources, not one kind + +- **An API and its SDKs are separate sources.** The API's changes come from its spec or its notices; an SDK's from its migration guide, its changelog, or its published files. Register each on its kind, under the same provider. +- **There is no kind per vendor or per tool.** Kubernetes API removals are a `migrationguide` or `notices` source; a Kubernetes client is a package source (`changelog` or `apisurface`); a Terraform provider is a `changelog` source. +- **Prefer the most machine-readable source** (a spec beats a changelog, a changelog beats a feed, a feed beats a blog post): [writing-a-plugin.md, step 2](writing-a-plugin.md#2-pick-the-source). + +Then scaffold it: `make new-plugin ARGS='--provider --source --kind '` ([step 1](writing-a-plugin.md#1-scaffold-it-with-new-plugin)). diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 62de359..bc7f703 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -1,29 +1,34 @@ # Writing a plugin -A **provider** (Stripe, OpenAI, Kubernetes…) has a **category** and one or more **sources**. A source is one place the provider announces changes; it is read by one **kind** of plugin (the `plugins/` package: `openapi`, `changelog`, `feed`, …), covers one **layer** (`api`, `sdk`, `package`, `runtime`, `ci`, `ai-models`, `infra`), and has **versions**. Its id is `provider/source` (`stripe/api`, `algolia/search-api`). This guide walks through adding a source, from picking it to the PR. The rules are in [CONTRIBUTING.md](../CONTRIBUTING.md); this is the how-to. How the pieces fit: [how-it-works.md](how-it-works.md). +A **provider** (Stripe, OpenAI, Kubernetes…) has a **category** and one or more **sources**. A source is one place the provider announces changes; it is read by one **kind** of plugin (the `plugins/` package: `openapi`, `changelog`, `notices`, `migrationguide`, `catalog`, `apisurface`), covers one **layer** (`api`, `sdk`, `package`, `runtime`, `ci`, `ai-models`, `infra`), and has **versions**. Its id is `provider/source` (`stripe/api`, `algolia/search-api`). This guide walks through adding a source, from picking it to the PR. The rules are in [CONTRIBUTING.md](../CONTRIBUTING.md); this is the how-to. How the pieces fit: [how-it-works.md](how-it-works.md). -**Most new sources don't need new code.** They are a new entry for an existing kind: a new `changelog.File`, a new `retire.Page`, a new `feed.Feed` reader, a new OpenAPI adapter. Write a new kind only when none of them reads your source. There is no "Kubernetes kind" or "Terraform kind": Kubernetes API removals are a migration-guide or notices source, a client SDK is a package source, a Terraform provider is a changelog source. +**Most new sources don't need new code.** They are a new entry for an existing kind: a new `changelog.File`, a new `retire.Page`, a new `feed.Feed` reader, a new OpenAPI adapter, a new `apisurface.Package`. Write a new kind only when none of them reads your source. There is no "Kubernetes kind" or "Terraform kind": Kubernetes API removals are a migration-guide or notices source, a client SDK is a package source, a Terraform provider is a changelog source. ## 1. Scaffold it with `new-plugin` -Pick the source and the kind that reads it (steps 2 and 3), then let the starter write everything around the provider: +Pick the source and the kind that reads it (steps 2 and 3, and [which kind fits my provider?](which-kind.md)), then let the starter write everything around it: ```sh -go run ./cmd/new-plugin --api acme --provider Acme --format openapi -# --format: openapi, retirements and feed (notices sources), migrationguide, removedmembers (a migrationguide source), -# changelog, apichangelog (a JSON changelog source), catalog -# optional: --source https://... (the provider's source), --watches "...", --layer api|sdk|package|runtime|ci|ai-models|infra, -# --page acme (a second source of a provider shares its page in providers/) +make new-plugin ARGS='--provider acme --name Acme --category devtools --homepage https://acme.example \ + --source api --kind openapi --url https://github.com/acme/openapi --package pypi:acme --package npm:acme' +# the same: go run ./cmd/new-plugin --provider acme ... +# --kind: openapi, changelog, notices, migrationguide, catalog, apisurface +# --reader, for a kind with several: changelog markdown|json, notices deprecations|feed, migrationguide sdk|members +# optional: --layer api|sdk|package|runtime|ci|ai-models|infra (default: the kind's), --watches "...", +# --page acme (share an existing providers/ page), --api acme-api (the first name; default -) ``` +Run in a terminal without the flags, it asks for them: the provider's id, then (for a new provider) its name, category and homepage, then the source's id, kind, reader, layer, URLs, packages and what it watches. A second source of a registered provider needs only `--provider`, `--source` and `--kind`: the name, category and homepage come from the registry. One run adds one source; run it again for the next. + It writes, and lists: -- the provider's definition, in the package the format reads it from (`plugins/openapi/adapter/`, `plugins/notices/retire/`, `plugins/notices/feed/`, `plugins/migrationguide/sdkguide/` or `plugins//`), and its `plugin.RegisterProvider` block (the provider and the source with their metadata) in that format's `init` (plus the `core/migrate/` map entry that the deprecations-page and SDK-guide readers need); -- `plugins//_test.go`: the registration test, a golden test and a pinned drop test, over placeholder sources in `testdata/`, with the golden file written from them; +- the source's definition in the package its kind reads it from (`plugins/openapi/adapter/`, `plugins/notices/retire/`, `plugins/notices/feed/`, `plugins/migrationguide/sdkguide/`, `plugins/migrationguide/members/` or `plugins//`), with the version wiring the kind needs from it: an OpenAPI adapter's `LatestTag`, `Fetch` and `Versions` to write; every other kind lists, reads and extracts versions itself; +- its `plugin.RegisterProvider` block (the provider and the source with every metadata field, packages included) in the kind's `init` (plus the `core/migrate/` map entry that the deprecations-page and SDK-guide readers need), and the kind's import in `plugins/all` if it's a new kind; +- `plugins//_test.go`: the registration test, a golden test and a pinned drop test, over placeholder sources in `testdata/`, with the golden file written from them; - a row per saved file in that `testdata/README.md` (URL, date, license, quote to fill in); -- `providers/.md` from the template (or nothing, with `--page`, when the provider already has one); +- `providers/.md` from the template (or nothing, with `--page`, when the provider already has one); -`go test ./...` passes right after; every place to fill in says `TODO(new-plugin)` (`grep -rn 'TODO(new-plugin)' .`), and `make check` (its `todos` step, also in CI_go) fails until none is left. It refuses an id that's taken (registered, or a file it would write exists) and then changes nothing. The steps below are what you fill in. +`go test ./...` passes right after; every place to fill in says `TODO(new-plugin)` (`grep -rn 'TODO(new-plugin)' .`), and `make check` (its `todos` step, also in CI_go) fails until none is left. It refuses a `provider/source` id or a first name that's taken, or a file it would write that exists, and then changes nothing. The old flags (`--api acme --provider Acme --format feed --source `) still work for one release. ## 2. Pick the source @@ -73,10 +78,12 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp ## 3. Pick the kind +[Which kind fits my provider?](which-kind.md) asks the questions; the table says what each kind reads. + | Kind | Reads | Add a source by | |---|---|---| | `plugins/openapi` | An OpenAPI spec per release, diffed with `core/diff/` and turned into events by `core/normalize/` | An `adapter.Adapter` in `plugins/openapi/adapter/` (latest tag, fetch a tag's spec; `Versions` to list every release) and a `plugin.RegisterProvider` block | -| `plugins/notices` | A live page of dated notices: a model provider's deprecations page (a table of date, model, replacement), a vendor's RSS or Atom feed, a vendor's table of whole API version ranges and their support status | A `retire.Page` in `plugins/notices/retire/providers.go`, a `feed.Feed` with a reader for that vendor's entries in `plugins/notices/feed/`, or an `eol.Page` in `plugins/notices/eol/` (`--format` doesn't scaffold this one yet) | +| `plugins/notices` | A live page of dated notices: a model provider's deprecations page (a table of date, model, replacement), a vendor's RSS or Atom feed, a vendor's table of whole API version ranges and their support status | A `retire.Page` in `plugins/notices/retire/providers.go`, a `feed.Feed` with a reader for that vendor's entries in `plugins/notices/feed/`, or an `eol.Page` in `plugins/notices/eol/` (`new-plugin` doesn't scaffold this reader yet) | | `plugins/migrationguide` | A guide that lists what a release removed, at the release's tag: an SDK's migration guide per new major (removed request parameters), or a package's table of removed members (an RST simple table or a Markdown pipe table) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/`, or a `members.Guide` in `plugins/migrationguide/members/` | | `plugins/changelog` | A changelog: a `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm), or a vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), commit by commit | A `changelog.File` with its `TagPrefix`, or a `changelog.Log` | | `plugins/catalog` | A flat JSON catalog, one entry per name, with no release tags to pin — a commit SHA stands in | A `catalog.Catalog`, diffed between two snapshots for names that disappeared entirely | diff --git a/plugins/all/all_test.go b/plugins/all/all_test.go index e4402a0..dc94d93 100644 --- a/plugins/all/all_test.go +++ b/plugins/all/all_test.go @@ -104,3 +104,17 @@ func TestEveryPluginIsASourceWithMetadata(t *testing.T) { } } } + +// Every registered source's kind is an answer of docs/which-kind.md, so the +// guide sends every source somewhere. +func TestWhichKindNamesEveryKind(t *testing.T) { + guide, err := os.ReadFile("../../docs/which-kind.md") + if err != nil { + t.Fatal(err) + } + for _, s := range plugin.Sources() { + if !strings.Contains(string(guide), "| `"+s.Source.Kind+"` |") { + t.Errorf("%s's kind, %s, isn't an answer in docs/which-kind.md", s.FullID(), s.Source.Kind) + } + } +} diff --git a/providers/algolia.md b/providers/algolia.md index 9158969..3b53b17 100644 --- a/providers/algolia.md +++ b/providers/algolia.md @@ -4,7 +4,7 @@ Three of Algolia's REST APIs, one plugin each: the Search API (`algolia-search`), the Ingestion API (`algolia-ingestion`) and the Recommend API (`algolia-recommend`). Each reports operations Algolia marks deprecated, and removals of operations it had marked deprecated, between two releases of that API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Algolia`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Algolia`. ## Why this source diff --git a/providers/anthropic.md b/providers/anthropic.md index cac9358..d67f50f 100644 --- a/providers/anthropic.md +++ b/providers/anthropic.md @@ -4,7 +4,7 @@ Request parameters removed from `messages.create()` and its siblings in anthropic-sdk-python 1.0.0 (`temperature`, `top_p`, `top_k`): passing one is a `TypeError`. One breaking event per parameter. Pinned to that release. -Format plugin: `migrationguide` (`plugins/migrationguide`), reading with `plugins/migrationguide/sdkguide/`. +Kind: `migrationguide` (`plugins/migrationguide`), reading with `plugins/migrationguide/sdkguide/`. ## Why this source diff --git a/providers/appwrite.md b/providers/appwrite.md index 1b44940..ea502e7 100644 --- a/providers/appwrite.md +++ b/providers/appwrite.md @@ -4,7 +4,7 @@ The Appwrite REST API as a server SDK calls it (the operations an Appwrite server SDK, in a repo's backend code, can call): operations Appwrite marks deprecated between two commits of its OpenAPI spec. SDK method renames that don't deprecate the route are left out, and so are removals. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Appwrite`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Appwrite`. ## Why this source diff --git a/providers/convex.md b/providers/convex.md index c848d5c..fb9e7db 100644 --- a/providers/convex.md +++ b/providers/convex.md @@ -4,7 +4,7 @@ The Convex Deployment API (`{deployment-url}/api/v1`, the platform API for managing one deployment: environment variables, log streams and integrations, usage limits, data sync): operations Convex marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Convex`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Convex`. ## Why this source diff --git a/providers/datadog.md b/providers/datadog.md index 9451a82..3de454b 100644 --- a/providers/datadog.md +++ b/providers/datadog.md @@ -4,7 +4,7 @@ Datadog's API v2, release by release: endpoints, request and response properties and schemas removed or changed between two versions of the OpenAPI spec Datadog generates its official clients from. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Datadog`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Datadog`. ## Why this source diff --git a/providers/elasticsearch.md b/providers/elasticsearch.md index c1dcdbf..36d6509 100644 --- a/providers/elasticsearch.md +++ b/providers/elasticsearch.md @@ -4,7 +4,7 @@ The Elasticsearch REST API, minor version by minor version: operations Elastic marks deprecated, and removals of operations it had marked deprecated, between two versions of the OpenAPI spec generated from Elastic's API specification. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Elasticsearch`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Elasticsearch`. ## Why this source diff --git a/providers/flagsmith.md b/providers/flagsmith.md index 40ff7ae..89ad8d0 100644 --- a/providers/flagsmith.md +++ b/providers/flagsmith.md @@ -4,7 +4,7 @@ Flagsmith's REST API (the Admin/Management API and the SDK-facing endpoints together) between releases of Flagsmith's own OpenAPI 3.1 spec: whole operations removed, and request parameters callers send that are removed, renamed or newly required. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Flagsmith` and a request-side filter (`openapi.Plugin.Keep`, same `requestSide` GitLab uses). +Kind: `openapi` (`plugins/openapi`), with `adapter.Flagsmith` and a request-side filter (`openapi.Plugin.Keep`, same `requestSide` GitLab uses). ## Why this source diff --git a/providers/github.md b/providers/github.md index 3bd5c02..f47fd93 100644 --- a/providers/github.md +++ b/providers/github.md @@ -4,7 +4,7 @@ GitHub's REST API between dated API versions (`2022-11-28` → `2026-03-10`): properties, schemas, parameters and operations removed or changed in a new version. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.GitHub`. +Kind: `openapi` (`plugins/openapi`), with `adapter.GitHub`. ## Why this source diff --git a/providers/gitlab.md b/providers/gitlab.md index c68d8d3..7556c13 100644 --- a/providers/gitlab.md +++ b/providers/gitlab.md @@ -4,7 +4,7 @@ GitLab's REST API (`/api/v4`) between releases, **request side only**: endpoints removed, and parameters callers send that are removed, renamed or newly required. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.GitLab` and a request-side filter (`openapi.Plugin.Keep`). +Kind: `openapi` (`plugins/openapi`), with `adapter.GitLab` and a request-side filter (`openapi.Plugin.Keep`). ## Why this source diff --git a/providers/neon.md b/providers/neon.md index 15bb787..1724564 100644 --- a/providers/neon.md +++ b/providers/neon.md @@ -4,7 +4,7 @@ The Neon API (`console.neon.tech/api/v2`), the management API for Neon projects, branches, computes, databases and roles: operations Neon marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Neon`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Neon`. ## Why this source diff --git a/providers/planetscale.md b/providers/planetscale.md index 4ff0a46..c1e9658 100644 --- a/providers/planetscale.md +++ b/providers/planetscale.md @@ -4,7 +4,7 @@ The PlanetScale API (`api.planetscale.com/v1`): operations PlanetScale marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. PlanetScale says it in the operation's description, never with the `deprecated` flag. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.PlanetScale`. +Kind: `openapi` (`plugins/openapi`), with `adapter.PlanetScale`. ## Why this source diff --git a/providers/redis.md b/providers/redis.md index 98808be..b7b9a84 100644 --- a/providers/redis.md +++ b/providers/redis.md @@ -4,7 +4,7 @@ Redis's command surface: commands that disappear entirely from `redis-doc`'s own catalog of every command, between two snapshots of it. -Format plugin: `catalog` (`plugins/catalog`), new in this change — no existing format plugin reads a flat JSON catalog keyed by name; see "Alternatives considered" for the formats checked and ruled out first. +Kind: `catalog` (`plugins/catalog`), new in this change — no existing format plugin reads a flat JSON catalog keyed by name; see "Alternatives considered" for the formats checked and ruled out first. ## Why this source diff --git a/providers/sentry.md b/providers/sentry.md index c851d03..d61f373 100644 --- a/providers/sentry.md +++ b/providers/sentry.md @@ -4,7 +4,7 @@ Sentry's public REST API (`https://{region}.sentry.io/api/0/...`): operations Sentry deprecates, between releases of its OpenAPI spec. Most of them it deprecates in the operation's description, not with the `deprecated` flag. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Sentry`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Sentry`. ## Why this source diff --git a/providers/stripe.md b/providers/stripe.md index 6c94bd1..46aee8f 100644 --- a/providers/stripe.md +++ b/providers/stripe.md @@ -4,7 +4,7 @@ Stripe's REST API, release by release: endpoints, parameters, fields, schemas and enum values that are removed, renamed, retyped or added between two versions of Stripe's own OpenAPI spec. Breaking events carry Stripe's own explanation from its API changelog as the migration hint when the changelog has one. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the changelog hint source in `hint/`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the changelog hint source in `hint/`. ## Why this source diff --git a/providers/supabase.md b/providers/supabase.md index 87ec785..86dae18 100644 --- a/providers/supabase.md +++ b/providers/supabase.md @@ -4,7 +4,7 @@ The Supabase Management API (`api.supabase.com/v1`): operations Supabase marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Supabase`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Supabase`. ## Why this source diff --git a/providers/textual.md b/providers/textual.md index 4b13089..ec6488b 100644 --- a/providers/textual.md +++ b/providers/textual.md @@ -4,7 +4,7 @@ Removals and breaking changes in each Textual release, read from that release's section of its changelog: symbols removed (`App.dark`, …) or renamed. One `package_release` event per changelog bullet the plugin can read with certainty. The releases are listed from PyPI (final releases only) and each is read at its tag (`v`); 0.86.0 is the release the golden test pins. -Format plugin: `changelog` (`plugins/changelog`). +Kind: `changelog` (`plugins/changelog`). ## Why this source diff --git a/providers/urllib3.md b/providers/urllib3.md index df1088c..d6c7e3d 100644 --- a/providers/urllib3.md +++ b/providers/urllib3.md @@ -4,7 +4,7 @@ Removals and deprecations in each urllib3 release, read from that release's section of its changelog: classes, methods and modules removed or renamed. One `package_release` event per bullet the plugin can read with certainty. The releases are listed from PyPI (final releases only) and each is read at its git tag (``); 2.0.0 is the release the golden test pins. -Format plugin: `changelog` (`plugins/changelog`). +Kind: `changelog` (`plugins/changelog`). ## Why this source diff --git a/providers/vercel.md b/providers/vercel.md index fb6e034..4aec983 100644 --- a/providers/vercel.md +++ b/providers/vercel.md @@ -4,7 +4,7 @@ Vercel's REST API, release by release: operations Vercel marks deprecated, and deprecated operations it then removes, between two versions of the OpenAPI spec Vercel generates its official SDK (`@vercel/sdk`) from. -Format plugin: `openapi` (`plugins/openapi`), with `adapter.Vercel`. +Kind: `openapi` (`plugins/openapi`), with `adapter.Vercel`. ## Why this source