Skip to content

I19 · Providers, sources and every version #171

Open
2 of 11 issues completed
Open

Description

@adssib

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 are provider/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), and Extract(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) and plugins/<kind>/, one package per kind.
  • No committed plugin list. The registry in code is the only list. docs/plugins.md, docs/plugins.json and the README's plugin table and count badge go away; patch-it's hosted service serves the list at GET /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/ and plugins/<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-plugin asks for a kind (S)
  • I19.8 · ListVersions, ReadAt and Extract for every kind; no pinned versions (M)
  • I19.9 · Backfill helpers (M)
  • I19.10 · apisurface kind: 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions