Repository navigation
Description
Goal
One model for every plugin, and every version captured, not only the newest.
Today each format plugin repeats the same pipeline in its own code, formats are named by the page they read (removedmembers, apichangelog), several plugins pin one release tag, and the list of plugins is written by hand in docs/plugins.md / docs/plugins.json and the README.
After this epic:
- A plugin is a provider with sources. A provider (Kubernetes, OpenAI, Stripe, ...) has a category (ai, payments, infrastructure, databases, monitoring, auth, messaging, hosting, devtools, ...) and one or more sources. Each source has its own kind (how it's read:
openapi,changelog,feed,migrationguide,notices,catalog,apisurface), layer (api,sdk,package,runtime,ci,ai-models,infra) and versions. Ids areprovider/source(openai/models,stripe/api,kubernetes/client-go); today's ids (openai-models, ...) stay as aliases until consumers switch. - Every source answers three questions:
ListVersions(git tags, GitHub releases, PyPI, npm, Go proxy, Maven, feed dates, or Wayback snapshots at a date),ReadAt(version), andExtract(versionA, versionB)→ changes. No version is pinned in code. - Layout:
core/(the contract types, the registry, version sources, fetch, cite, event types, the test kit) andplugins/<kind>/, one package per kind. - No committed plugin list. The registry in code is the only list.
docs/plugins.md,docs/plugins.jsonand the README's plugin table and count badge go away; patch-it's hosted service serves the list atGET /v1/plugins, and docs link to it. - Short README: what it is in two lines, three steps to start, links. Details move to
docs/. - Backfill helpers: given a version range, a source can be read at every version in it, so older pairs can be filled in later.
Golden files stay byte-identical in every PR, except the one PR that adopts the change-event contract change (owned by patch-it: previous_version required for version-pair events, provider/source ids). That PR regenerates them and says why, file by file.
Stories
Sub-issues of this epic:
- I19.1 · Design: providers, sources, kinds and versions (S)
- I19.2 · Provider and source metadata in the registry; no committed plugin list (M)
- I19.3 ·
core/andplugins/<kind>/layout (M) - I19.4 · One migration-guide kind (M)
- I19.5 · One changelog kind (M)
- I19.6 · One notices kind (M)
- I19.7 · Short README, "which kind fits my source?" guide,
new-pluginasks for a kind (S) - I19.8 · ListVersions, ReadAt and Extract for every kind; no pinned versions (M)
- I19.9 · Backfill helpers (M)
- I19.10 ·
apisurfacekind: a package's public API between versions (L) - I19.11 · Wayback-at-date version source (S)
Outside this repo: the change-event contract (patch-it) changes first; patch-it's hosted service stores every version pair and serves GET /v1/plugins; the client asks for the changes between two versions and opens one PR per major.
Timing
I18 adds infrastructure sources. Kubernetes API removals are a migrationguide or notices source, Kubernetes client SDKs are package sources, and Terraform providers are changelog sources: no Kubernetes or Terraform kind. I18 stories that reuse an existing kind as-is can go ahead; the move keeps them working.
Done when
Every story's acceptance criteria are met, goldens are byte-identical except the one contract PR, and the docs that describe the behavior are updated in the same PRs.
Activity
[-]I19 · One plugin pipeline, one source of truth[/-][+]I19 · Providers, sources and every version[/+]