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
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,10 @@ core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Page
core/event/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2
core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers
plugins/<kind>/ one package per kind, with its providers: openapi (+ adapter/, one spec adapter
per provider), retirements (+ retire/), migrationguide (+ sdkguide/),
removedmembers, changelog, feed, apichangelog, catalog, eol;
per provider), retirements (+ retire/), migrationguide (+ sdkguide/,
members/), changelog, feed, apichangelog, catalog, eol;
plugins/all imports every one
plugins/removedmembers/ deprecated: merged into migrationguide, only forwards there
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
Expand Down
27 changes: 18 additions & 9 deletions cmd/new-plugin/formats.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ package main
// definition goes, the line that registers it, the placeholder sources its
// test reads, and how the test runs it.
type formatSpec struct {
kind string // the kind: the plugins/<kind> package that registers and tests it
layer string // the source's default layer (plugin.Layers())
defDir string // the package directory the definition goes in
def string // the definition file (template)
Expand All @@ -30,6 +31,7 @@ const todo = "TODO(new-plugin)"

var formats = map[string]formatSpec{
"feed": {
kind: "feed",
layer: "api",
defDir: "plugins/feed",
def: `package feed
Expand Down Expand Up @@ -80,6 +82,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"retirements": {
kind: "retirements",
layer: "ai-models",
defDir: "plugins/retirements/retire",
def: `package retire
Expand Down Expand Up @@ -153,6 +156,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"migrationguide": {
kind: "migrationguide",
layer: "sdk",
defDir: "plugins/migrationguide/sdkguide",
def: `package sdkguide
Expand Down Expand Up @@ -219,9 +223,10 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"removedmembers": {
kind: "migrationguide",
layer: "package",
defDir: "plugins/removedmembers",
def: `package removedmembers
defDir: "plugins/migrationguide/members",
def: `package members

// {{.Ident}} is {{.Provider}}'s migration guide to a release, with its table
// of removed members.
Expand All @@ -238,8 +243,8 @@ var {{.Ident}} = Guide{
Section: "Removed members",
}
`,
register: `plugin.Register(Plugin{Guide: {{.Ident}}})`,
pluginOf: `Plugin{Guide: {{.Ident}}}`,
register: `plugin.Register(Plugin{Guide: members.{{.Ident}}})`,
pluginOf: `Plugin{Guide: members.{{.Ident}}}`,
fixtures: map[string]string{"{{.File}}-migration-guide.rst": `.. ` + todo + `: a placeholder. Replace it with a real copy of the guide at the release tag and list it in README.md.

Removed members
Expand Down Expand Up @@ -278,7 +283,7 @@ placeholder_elsewhere Not in the main table.
func Test{{.Ident}}DropsANonChange(t *testing.T) {
for _, e := range {{.Lower}}Ingest(t, {{.Lower}}Drop) {
if slices.Contains(e.Subject.Symbols, "placeholder_elsewhere") {
t.Errorf("event for placeholder_elsewhere, which isn't under %q", {{.Ident}}.Section)
t.Errorf("event for placeholder_elsewhere, which isn't under %q", members.{{.Ident}}.Section)
}
}
}
Expand All @@ -287,13 +292,14 @@ func Test{{.Ident}}DropsANonChange(t *testing.T) {
ingest: `// {{.Lower}}Ingest runs the plugin over a saved copy of the guide.
func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
t.Helper()
return kittest.Ingest(t, Plugin{Guide: {{.Ident}}}, kittest.Pages{ {{.Ident}}.URL(): file})
return kittest.Ingest(t, Plugin{Guide: members.{{.Ident}}}, kittest.Pages{members.{{.Ident}}.URL(): file})
}
`,
imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/core/event"},
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": {
kind: "changelog",
layer: "package",
defDir: "plugins/changelog",
def: `package changelog
Expand Down Expand Up @@ -335,6 +341,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"apichangelog": {
kind: "apichangelog",
layer: "api",
defDir: "plugins/apichangelog",
def: `package apichangelog
Expand Down Expand Up @@ -372,6 +379,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"catalog": {
kind: "catalog",
layer: "runtime",
defDir: "plugins/catalog",
def: `package catalog
Expand Down Expand Up @@ -421,6 +429,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"openapi": {
kind: "openapi",
layer: "api",
defDir: "plugins/openapi/adapter",
def: `package adapter
Expand Down Expand Up @@ -497,7 +506,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
}

// testFile is the generated test, the same for every format.
const testFile = `package {{.Format}}
const testFile = `package {{.Kind}}

import (
{{range .Imports}} "{{.}}"
Expand All @@ -518,7 +527,7 @@ func Test{{.Ident}}RegistersItself(t *testing.T) {
// The golden test: the saved source in, every event out.
// ` + todo + `: once the source is real, run
//
// go test ./plugins/{{.Format}} -run Test{{.Ident}}Golden -update
// go test ./plugins/{{.Kind}} -run Test{{.Ident}}Golden -update
//
// and read testdata/golden/{{.ID}}.json like code: every event in it is a
// pull request someone may get.
Expand Down
20 changes: 10 additions & 10 deletions cmd/new-plugin/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,10 +94,10 @@ var (

// data is what the templates fill in.
type data struct {
ID, Ident, Lower, Provider, Source, File, Format 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 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.
Expand Down Expand Up @@ -143,7 +143,7 @@ func Run(o Options, out io.Writer) error {
return fmt.Errorf("a plugin named %q is already registered: pick another --api", o.API)
}

d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format}
d := data{ID: o.API, Provider: o.Provider, Source: o.Source, Format: o.Format, Kind: f.kind}
d.Ident = ident(o.API)
d.Lower = string(unicode.ToLower(rune(d.Ident[0]))) + d.Ident[1:]
d.File = fileBase(o.API)
Expand All @@ -156,7 +156,7 @@ func Run(o Options, out io.Writer) error {
d.Imports = append(slices.Clone(f.imports), "testing", "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest")
slices.Sort(d.Imports)

pkgDir := "plugins/" + o.Format
pkgDir := "plugins/" + f.kind
writes := map[string][]byte{}
add := func(path string, b []byte) { writes[path] = b }

Expand Down Expand Up @@ -267,13 +267,13 @@ func Run(o Options, out io.Writer) error {
const nextSteps = `
Next steps (every place to fill in says TODO(new-plugin): grep -rn 'TODO(new-plugin)' .):
1. Save a real copy of the source over the placeholder:
curl -fsSL -o plugins/{{.Format}}/testdata/{{.SourceFile}} '<the source URL>'
and a realistic input that must not become an event as plugins/{{.Format}}/testdata/{{.DropFile}}.
Fill in their rows in plugins/{{.Format}}/testdata/README.md (URL, date fetched, license, quote).
curl -fsSL -o plugins/{{.Kind}}/testdata/{{.SourceFile}} '<the source URL>'
and a realistic input that must not become an event as plugins/{{.Kind}}/testdata/{{.DropFile}}.
Fill in their rows in plugins/{{.Kind}}/testdata/README.md (URL, date fetched, license, quote).
2. Fill in the definition (the TODOs in the file next to the Register line for {{.Ident}}).{{if .Extra}}
{{.Extra}}{{end}}
3. Write the golden file, then read it like code:
go test ./plugins/{{.Format}} -run Test{{.Ident}} -update
go test ./plugins/{{.Kind}} -run Test{{.Ident}} -update
4. {{if .Shared}}Add {{.ID}} to providers/{{.Page}}.md (shared with the provider's other plugins){{else}}Fill in providers/{{.Page}}.md{{end}}, above all "Why this source", and the source's
metadata in its RegisterProvider block (what it watches, its URLs; a new provider's category and
homepage). go run ./cmd/list-plugins prints the list with it; there is no list to edit.
Expand Down
18 changes: 17 additions & 1 deletion core/plugin/provider.go
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ func (p Provider) check() error {
return fmt.Errorf("source %q has no URLs", id)
case !strings.HasPrefix(s.Page, "providers/") || !strings.HasSuffix(s.Page, ".md"):
return fmt.Errorf("source %q: Page %q isn't providers/<name>.md", id, s.Page)
case s.Kind != "" && s.Kind != KindOf(s.Plugin):
case s.Kind != "" && CanonicalKind(s.Kind) != KindOf(s.Plugin):
return fmt.Errorf("source %q: Kind %q, but its plugin is in plugins/%s", id, s.Kind, KindOf(s.Plugin))
}
for _, u := range s.URLs {
Expand Down Expand Up @@ -232,6 +232,22 @@ func KindOf(p Plugin) string {
return path.Base(t.PkgPath())
}

// mergedKinds are the kinds merged into another, by their old name: what
// they read is read by the new kind, with the same events.
var mergedKinds = map[string]string{
"removedmembers": "migrationguide",
}

// CanonicalKind is the kind name means now: name itself, or, for a kind
// merged into another ("removedmembers"), the kind that reads its sources
// now ("migrationguide"). Code that still says an old kind keeps working.
func CanonicalKind(name string) string {
if k, ok := mergedKinds[name]; ok {
return k
}
return name
}

// Providers are the registered providers with their sources, sorted by id
// (sources by id within each).
func Providers() []Provider {
Expand Down
13 changes: 13 additions & 0 deletions core/plugin/provider_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,3 +82,16 @@ func TestRegisterProviderRefusesConflictingProvider(t *testing.T) {
p.Name = "Acme Corp"
RegisterProvider(p)
}

// A kind merged into another still names it: a source registered with the
// old name passes the check, and the old name reads as the new one.
func TestMergedKindsKeepWorking(t *testing.T) {
for old, now := range mergedKinds {
if got := CanonicalKind(old); got != now {
t.Errorf("CanonicalKind(%q) = %q, want %q", old, got, now)
}
}
if got := CanonicalKind("openapi"); got != "openapi" {
t.Errorf("CanonicalKind(openapi) = %q", got)
}
}
4 changes: 2 additions & 2 deletions docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@ There's no list in this repo: `make plugins` prints every provider and source fr
| [`core/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub) and the test kit (in-memory store, saved pages, golden files) |
| [`core/event/`](../core/event/), [`core/migrate/`](../core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion |
| [`core/diff/`](../core/diff/), [`core/normalize/`](../core/normalize/), [`core/hint/`](../core/hint/), [`plugins/openapi/adapter/`](../plugins/openapi/adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider |
| [`plugins/retirements/retire/`](../plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`core/fetch/`](../core/fetch/) | The deprecations-page and migration-guide readers; the HTTP fetch and cache |
| [`plugins/retirements/retire/`](../plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The deprecations-page and migration-guide readers (removed parameters, removed members); the HTTP fetch and cache |
| [`contract/fixtures/`](../contract/) | A copy of patch-it's change-event fixtures |
| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves |
| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/`, `plugins/removedmembers/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves |
| [`providers/`](../providers/) | One page per provider: why that source, what the plugin reads |
| [`docs/`](./) | [How to write a plugin](writing-a-plugin.md), the [README template](README-template.md) patch-it's public repos share |

Expand Down
2 changes: 1 addition & 1 deletion docs/plugins.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
"properties": {
"id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$", "description": "provider/source" },
"alias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$", "description": "The old slug: --api and every event's api field until patch-it's change-event contract switches to source ids." },
"kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "removedmembers", "changelog", "feed", "apichangelog", "catalog", "eol"] },
"kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "changelog", "feed", "apichangelog", "catalog", "eol"] },
"layer": { "type": "string", "enum": ["api", "sdk", "package", "runtime", "ci", "ai-models", "infra"] },
"watches": { "type": "string", "minLength": 1 },
"urls": { "type": "array", "items": { "type": "string", "pattern": "^https://" } },
Expand Down
5 changes: 2 additions & 3 deletions docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Pick the source and the kind that reads it (steps 2 and 3), then let the starter

```sh
go run ./cmd/new-plugin --api acme --provider Acme --format openapi
# --format: openapi, retirements, migrationguide, removedmembers, changelog, feed, apichangelog, catalog
# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, apichangelog, 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/)
```
Expand Down Expand Up @@ -76,8 +76,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp
|---|---|---|
| `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/retirements` | A model provider's deprecations page (a table of date, model, replacement) | A `retire.Page` in `plugins/retirements/retire/providers.go` |
| `plugins/migrationguide` | An SDK's migration guide at the tag of each new major (removed request parameters) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/` |
| `plugins/removedmembers` | A package's table of removed members at a release tag (an RST simple table or a Markdown pipe table) | A `removedmembers.Guide` |
| `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.md` / `CHANGES.rst` / `HISTORY.rst`, each release's section at its tag (releases from PyPI or npm) | A `changelog.File` with its `TagPrefix` |
| `plugins/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries |
| `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 |
Expand Down
3 changes: 2 additions & 1 deletion internal/pluginlist/schema_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,8 @@ func TestSchemaEnumsMatchTheRegistry(t *testing.T) {
t.Fatal(err)
}
for _, k := range kinds {
if name := filepath.Base(k); name != "all" && !slices.Contains(src["kind"].Enum, name) {
// A merged kind's old package only forwards: no source has its name.
if name := filepath.Base(k); name != "all" && plugin.CanonicalKind(name) == name && !slices.Contains(src["kind"].Enum, name) {
t.Errorf("kind %s is missing from the schema's kind enum", name)
}
}
Expand Down
1 change: 0 additions & 1 deletion plugins/all/all.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,5 @@ import (
_ "github.com/patch-it-dev/patch-it-plugins/plugins/feed"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/openapi"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/removedmembers"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/retirements"
)
11 changes: 11 additions & 0 deletions plugins/migrationguide/members/export_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
package members

// What the external tests (package members_test, which can import the kind
// that imports this package) reach of the unexported helpers.
var (
PipeCells = pipeCells
SoleName = soleName
)

func (g Guide) Tag() string { return g.tag() }
func (g Guide) AbsoluteLinks(s string) string { return g.absoluteLinks(s) }
18 changes: 18 additions & 0 deletions plugins/migrationguide/members/golden_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
package members_test

import (
"testing"

"github.com/patch-it-dev/patch-it-plugins/core/kit/kittest"

"github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide"
. "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test
)

// The guide at tag v2.0.0 (saved 2026-11-04) in, every event out.
func TestGolden(t *testing.T) {
got := kittest.Ingest(t, migrationguide.Plugin{Guide: NumPy2}, kittest.Pages{
NumPy2.URL(): "testdata/numpy_2_0_migration_guide-v2.0.0.rst",
})
kittest.Golden(t, "../testdata/golden/numpy-2.0.0.json", got)
}
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package removedmembers
package members

import (
"fmt"
Expand Down
Loading
Loading