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
11 changes: 6 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,15 +53,16 @@ core/plugin/ the Plugin interface (Run; ListVersions, ReadAt, Extract)
core/fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache
core/github/ the newest release / commit on GitHub, and a commit's SHA and date (one place)
core/versions/ every version of a source: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date
core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden)
core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback, Notices; the test kit (Mem, Pages, Ingest, Golden)
core/extract/ what readers of prose share: RSS/Atom entries, HTML as text, dates, code spans
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/,
members/), changelog (Markdown, RST or JSON), feed, catalog, eol;
per provider), notices (+ retire/, feed/, eol/), migrationguide (+ sdkguide/,
members/), changelog (Markdown, RST or JSON), catalog;
plugins/all imports every one
plugins/removedmembers/ plugins/apichangelog/ deprecated: merged into migrationguide and
changelog, they only forward there
plugins/removedmembers/ apichangelog/ retirements/ feed/ eol/ deprecated: merged into
migrationguide, changelog and notices, they only forward 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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ You need Go (the version in `go.mod`), `make` and Python 3.
```
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:
```sh
go test ./plugins/feed -run TestAcme -update
go test ./plugins/notices -run TestAcme -update
```
3. **Check it the way CI will, and open the PR** (`git commit -s`, one provider per PR):
```sh
Expand Down
20 changes: 10 additions & 10 deletions cmd/new-plugin/formats.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ const todo = "TODO(new-plugin)"

var formats = map[string]formatSpec{
"feed": {
kind: "feed",
kind: "notices",
layer: "api",
defDir: "plugins/feed",
defDir: "plugins/notices/feed",
def: `package feed

// {{.Ident}} is {{.Provider}}'s feed of changes.
Expand All @@ -60,8 +60,8 @@ func read{{.Ident}}(e Entry) []Finding {
return nil
}
`,
register: `plugin.Register(Plugin{Feed: {{.Ident}}, Archiver: kit.Wayback{}})`,
pluginOf: `Plugin{Feed: {{.Ident}}}`,
register: `plugin.Register(Plugin{Page: feed.{{.Ident}}, Archiver: kit.Wayback{}})`,
pluginOf: `Plugin{Page: feed.{{.Ident}}}`,
fixtures: map[string]string{"{{.File}}.rss.xml": `<?xml version="1.0" encoding="UTF-8"?>
<!-- ` + todo + `: a placeholder. Replace it with a real copy of {{.Source}} (curl -o) and list it in README.md. -->
<rss version="2.0"><channel><title>placeholder</title><link>https://example.com/</link><description>placeholder</description>
Expand All @@ -73,18 +73,18 @@ func read{{.Ident}}(e Entry) []Finding {
// through a test archive that serves the same copy.
func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
t.Helper()
saved := kittest.Pages{ {{.Ident}}.URL: file}
saved := kittest.Pages{feed.{{.Ident}}.URL: file}
archive := &kittest.Archive{T: t, Pages: saved}
return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: {{.Ident}}, Archiver: archive})
return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: feed.{{.Ident}}, Archiver: archive})
}
`,
imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"},
imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/notices/feed"},
},

"retirements": {
kind: "retirements",
kind: "notices",
layer: "ai-models",
defDir: "plugins/retirements/retire",
defDir: "plugins/notices/retire",
def: `package retire

import "strings"
Expand Down Expand Up @@ -152,7 +152,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: retire.{{.Ident}}, Archiver: archive})
}
`,
imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire"},
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": {
Expand Down
10 changes: 7 additions & 3 deletions plugins/feed/parse.go → core/extract/feed.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
package feed
// Package extract is what readers of prose share: an RSS or Atom feed's
// entries, an HTML fragment as plain text or lines, its sections by
// heading, a "Month D, YYYY" date, the code spans in it. A reader of any
// kind uses it; it knows no vendor.
package extract

import (
"bytes"
Expand Down Expand Up @@ -53,10 +57,10 @@ type atom struct {
} `xml:"entry"`
}

// Parse reads an RSS 2.0 or Atom feed, whichever the root element says. A
// ParseFeed reads an RSS 2.0 or Atom feed, whichever the root element says. A
// feed with no entries is an error: a feed that moved or changed shape must
// not read as a quiet week.
func Parse(b []byte) ([]Entry, error) {
func ParseFeed(b []byte) ([]Entry, error) {
var root struct{ XMLName xml.Name }
if err := xml.NewDecoder(bytes.NewReader(b)).Decode(&root); err != nil {
return nil, fmt.Errorf("not a feed: %w", err)
Expand Down
11 changes: 11 additions & 0 deletions core/kit/notices.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
package kit

// Notices is what a reader of a live page of dated notices (a deprecations
// table, an end-of-life table, a feed: plugins/notices) found on one read
// of it. The kind compares what the live page and its snapshot give with
// reflect.DeepEqual (Cite), so a Notices holds plain values, never a func.
type Notices interface {
// Count is how many notices were read: what the shape guard compares
// with the last read.
Count() int
}
2 changes: 1 addition & 1 deletion core/migrate/migrate.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import (

"github.com/patch-it-dev/patch-it-plugins/core/event"
"github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide"
"github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire"
"github.com/patch-it-dev/patch-it-plugins/plugins/notices/retire"
)

// providers are the model retirement slugs and who retires the models.
Expand Down
3 changes: 3 additions & 0 deletions core/plugin/provider.go
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,9 @@ func KindOf(p Plugin) string {
var mergedKinds = map[string]string{
"removedmembers": "migrationguide",
"apichangelog": "changelog",
"retirements": "notices",
"feed": "notices",
"eol": "notices",
}

// CanonicalKind is the kind name means now: name itself, or, for a kind
Expand Down
6 changes: 3 additions & 3 deletions docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,12 @@ There's no list in this repo: `make plugins` prints every provider and source fr
| [`core/versions/`](../core/versions/) | Every version of a source: GitHub releases, tags and commits, PyPI, npm, the Web Archive at a date |
| [`plugins/`](../plugins/) | One package per kind, with its providers; `plugins/all` imports every one |
| [`cmd/new-plugin/`](../cmd/new-plugin/), [`cmd/list-plugins/`](../cmd/list-plugins/) | The starter for a new provider; the list of providers and sources, printed from the registry |
| [`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/kit/`](../core/kit/), [`core/kit/kittest/`](../core/kit/kittest/), [`core/github/`](../core/github/), [`core/extract/`](../core/extract/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub, RSS/Atom and HTML text helpers) 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/), [`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 |
| [`plugins/notices/retire/`](../plugins/notices/retire/), [`plugins/notices/feed/`](../plugins/notices/feed/), [`plugins/notices/eol/`](../plugins/notices/eol/), [`plugins/migrationguide/sdkguide/`](../plugins/migrationguide/sdkguide/), [`plugins/migrationguide/members/`](../plugins/migrationguide/members/), [`core/fetch/`](../core/fetch/) | The notices readers (deprecations pages, feeds, end-of-life tables) and the 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/`, `plugins/removedmembers/`, `plugins/apichangelog/` | 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/`, `plugins/apichangelog/`, `plugins/retirements/`, `plugins/feed/`, `plugins/eol/` | 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", "changelog", "feed", "catalog", "eol"] },
"kind": { "type": "string", "enum": ["openapi", "changelog", "notices", "migrationguide", "catalog"] },
"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
11 changes: 5 additions & 6 deletions docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,15 @@ 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 (a migrationguide source), changelog, feed, apichangelog (a JSON changelog source), catalog
# --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/)
```

It writes, and lists:

- the provider's definition, in the package the format reads it from (`plugins/openapi/adapter/`, `plugins/retirements/retire/`, `plugins/migrationguide/sdkguide/` or `plugins/<format>/`), 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 `retirements` and `migrationguide` need);
- 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/<format>/`), 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/<format>/<api>_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/<api>.md` from the template (or nothing, with `--page`, when the provider already has one);
Expand Down Expand Up @@ -75,12 +76,10 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp
| 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/retirements` | A model provider's deprecations page (a table of date, model, replacement) | A `retire.Page` in `plugins/retirements/retire/providers.go` |
| `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/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/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 |
| `plugins/eol` | A vendor's own table of whole API version ranges and their support status (supported, deprecated, retired) | An `eol.Page`; `--format` doesn't scaffold this one yet, write it by hand |

## 4. The interface

Expand Down Expand Up @@ -160,7 +159,7 @@ The event format is [patch-it's change-event contract](https://github.com/patch-

## 5. Save the source

Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `plugins/retirements/retire/testdata/`). Add a row to that directory's `README.md`: file, URL, date fetched, license, and a short quote of the part the plugin reads.
Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `plugins/notices/retire/testdata/`). Add a row to that directory's `README.md`: file, URL, date fetched, license, and a short quote of the part the plugin reads.

- **Openly licensed files** (MIT, BSD, Apache, CC BY): keep them whole.
- **Vendor documentation pages**: trim to what the plugin reads (the tables, the sections), copy every kept line unchanged, mark it "excerpt for testing; © the vendor", and say what you left out.
Expand Down
4 changes: 1 addition & 3 deletions plugins/all/all.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@ package all
import (
_ "github.com/patch-it-dev/patch-it-plugins/plugins/catalog"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/changelog"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/eol"
_ "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/notices"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/openapi"
_ "github.com/patch-it-dev/patch-it-plugins/plugins/retirements"
)
Loading
Loading