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
131 changes: 23 additions & 108 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@

# patch-it-plugins

**How patch-it notices, on its own, that something your code depends on changed.** Each plugin watches one provider's own source (an API spec, a changelog, a shutdown notice, a release feed) and turns what changed into a change event, with the source linked and quoted.

**Why:** when anything your code depends on changes (APIs, packages, SDKs, runtimes, CI, AI models), [patch-it](https://patch-it.dev) finds the code that breaks and opens the pull request that fixes it. In your CI, on your key. You get the fix, not the alert. These plugins are the trigger: nobody has to assign an alert or open a ticket.
**How patch-it notices, on its own, that something your code depends on changed.** Each provider (Stripe, OpenAI, GitHub…) has sources (a spec, a changelog, a shutdown notice, a feed); a plugin reads every version of a source and turns what changed into a change event, with the source linked and quoted.

[![CI](https://github.com/patch-it-dev/patch-it-plugins/actions/workflows/CI_go.yml/badge.svg)](https://github.com/patch-it-dev/patch-it-plugins/actions/workflows/CI_go.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins)
Expand All @@ -13,110 +11,27 @@
[![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev)
[![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions)

```mermaid
flowchart LR
A["Provider's own source<br/>spec · changelog · shutdown notice · feed"] -->|"read daily"| B["Plugin<br/>(this repo)"]
B -->|"what changed, quoted"| C["Change event<br/>breaking · deprecation · date · source"]
C --> D["patch-it in your CI<br/>finds the lines, an AI model writes the change"]
D --> E["Pull request in your repo<br/>your CI runs your tests, you merge it"]
```

## What patch-it does

1. **It notices on its own.** A plugin here sees the change where the provider announces it, and patch-it picks it up from there: no alert to triage, no ticket to assign. That includes changes that never bump a version, like an AI model or an API shut down on a date.
2. **It writes the fix.** An AI model (on your own key) reads the change and the lines it affects and writes the code change. It arrives as a pull request: your CI runs your tests on it, like any PR, and you review and merge it. The code change, not just the version.
3. **Proof:** 8 pull requests opened by the early version have been merged by outside maintainers.
4. **What it covers:** APIs, AI models, packages and SDKs, runtimes and CI. The current list of providers and sources is generated from the code: see [docs.patch-it.dev](https://docs.patch-it.dev/supported-apis/plugins/), or run `make plugins`.

5. **Start:** [docs.patch-it.dev](https://docs.patch-it.dev) sets up the GitHub Action in your repo. To have it watch a provider it doesn't cover yet, add a plugin (below).

## Add a provider in 15 minutes

You need Go (the version in `go.mod`), `make` and Python 3. Pick the format that reads your provider's source ([which one](docs/writing-a-plugin.md#3-pick-the-format-plugin)), then:

**1. Scaffold it.**

```sh
URL=https://acme.example/changelog.xml # your provider's source
go run ./cmd/new-plugin --api acme --provider Acme --format feed --source "$URL"
```
```
Scaffolded acme (Acme, format feed):
plugins/feed/acme.go (new)
plugins/feed/acme_test.go (new)
...
Next steps (every place to fill in says TODO(new-plugin): ...)
```

**2. Save a real copy of the source and write the golden file.** Fill in the `TODO(new-plugin)`s: the reader in `plugins/feed/acme.go`, the saved file's row in `testdata/README.md`, and "Why this source" in `providers/acme.md`.

```sh
curl -fsSL -o plugins/feed/testdata/acme.rss.xml "$URL"
go test ./plugins/feed -run TestAcme -update # writes testdata/golden/acme.json: read it like code
```

**3. Check it, the way CI will.**

```sh
make check
```
```
...
make check: all passed
```

**4. Open the pull request** (`git commit -s`, one plugin per PR). Details: [docs/writing-a-plugin.md](docs/writing-a-plugin.md). Stuck? Ask in [Discussions](https://github.com/patch-it-dev/patch-it-plugins/discussions). Looking for a first change? [Good first issues](https://github.com/patch-it-dev/patch-it-plugins/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

## How a plugin works

1. **Fetch.** The plugin asks its environment for the source (`env.Get`); it never opens connections itself. Pages that change in place are also cited through a Web Archive snapshot, so the link in an event keeps showing what the plugin read.
2. **Compare.** It compares the source to the last version it saw (the baseline): two OpenAPI specs, two versions of a deprecations page, a new release's changelog section.
3. **Emit events.** Each change becomes one event in [patch-it's change-event format](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract): what changed, how bad it is (breaking, deprecation, behavior change, non-breaking), the date it takes effect, and the source URL with a quote. **No source, no event.** When unsure, a plugin emits nothing: a wrong event would become a wrong pull request.

Most providers are an entry for a shared format plugin (`openapi`, `retirements`, `migrationguide`, `removedmembers`, `changelog`, `feed`, `apichangelog`, `catalog`), not new code. patch-it's hosted ingestion service runs every plugin daily and serves the events to the patch-it GitHub Action and CLI.

## Supported plugins

There's no list in this repo: each provider and source is registered in code with its metadata (`plugin.RegisterProvider`). `make plugins` prints the list as JSON, every release attaches it as `plugins.json`, and [docs.patch-it.dev](https://docs.patch-it.dev/supported-apis/plugins/) shows it.

## Layout

| Path | What's there |
|---|---|
| [`core/plugin/`](core/plugin/) | The `Plugin` interface, the registry (`Register`, `Lookup`, `Names`), `Env`, `Result` |
| [`plugins/`](plugins/) | The format plugins; `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/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 |
| [`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 |
| [`providers/`](providers/) | One page per provider: why that source, what the plugin reads |
| [`docs/`](docs/) | [How to write a plugin](docs/writing-a-plugin.md), the [README template](docs/README-template.md) patch-it's public repos share |

## Run the checks

```sh
make check # what CI runs: tidy, build, gofmt, vet, import and net/http guards, go test -race, no TODO(new-plugin) left, leak guard
```

The tests are offline: every plugin's test reads a saved copy of its source from `testdata/` and compares the events with a golden file. After an intended change to a plugin's output, `go test ./plugins/<name> -update` rewrites its golden files; review that diff like code.

`GITHUB_TOKEN` (optional, no scopes) only raises GitHub's rate limit when the `openapi` adapters look up release tags; the tests never use it. Nothing else is read from the environment.

## Releases

Releases are `v0.x.y` tags on `main` with a [GitHub release](https://github.com/patch-it-dev/patch-it-plugins/releases) and generated notes. The **Release** workflow tags a patch release on its own every Monday and Thursday at 14:00 UTC when something new was merged, and maintainers can run it by hand ([how](CONTRIBUTING.md#releasing)). patch-it's hosted ingestion service runs the latest release, so a merged plugin is running within a few days. Tags are never moved or deleted.

```sh
go get github.com/patch-it-dev/patch-it-plugins@latest
```

## Contributing

New providers and fixes are welcome: [CONTRIBUTING.md](CONTRIBUTING.md) has the rules (DCO sign-off, golden tests, the plugin list), [docs/writing-a-plugin.md](docs/writing-a-plugin.md) the how-to. AI coding agents: [AGENTS.md](AGENTS.md). Questions and ideas: [Discussions](https://github.com/patch-it-dev/patch-it-plugins/discussions).

## License

[Apache-2.0](LICENSE), copyright patch-it contributors.
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)):
```sh
go run ./cmd/new-plugin --api acme --provider Acme --format feed --source 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:
```sh
go test ./plugins/feed -run TestAcme -update
```
3. **Check it the way CI will, and open the PR** (`git commit -s`, one provider per PR):
```sh
make check
```

## More

- [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).
- What patch-it does with the events: [patch-it.dev](https://patch-it.dev) and [docs.patch-it.dev](https://docs.patch-it.dev). [Apache-2.0](LICENSE), copyright patch-it contributors.
64 changes: 15 additions & 49 deletions docs/README-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,16 @@ Every public patch-it repo's README has the same shape, so a developer landing o

## The sections, in order

A README is **one screen**. Everything else goes in `docs/` and is linked.

| # | Section | What goes in it |
|---|---|---|
| 1 | **What** (one line, bold, under the title) | What *this repo* is, in one sentence, in the product's words. For a part of patch-it, say which part of the story it is ("how patch-it notices, on its own, that something changed"). |
| 2 | **Why** (one short paragraph) | The one-liner for patch-it: when anything your code depends on changes (APIs, packages, SDKs, runtimes, CI, AI models), patch-it finds the code that breaks and opens the pull request that fixes it. In your CI, on your key. "You get the fix, not the alert." Then one sentence on why this repo matters to that. |
| 3 | **Badges** (one line of them) | The badge set below, in that order. |
| 4 | **Visual** | One picture of the flow: a mermaid diagram (GitHub renders it) until there's a GIF or screenshot. Left to right, ending in "pull request in your repo". |
| 5 | **The story** ("What patch-it does") | In this order, one or two lines each: (1) **it notices on its own** (it watches the change itself; no one assigns an alert; also changes with no version bump, like a model or API shut down on a date); (2) **it writes the fix** (an AI model on your key writes the code change, your CI runs your tests on the pull request like any PR, you review and merge it; never say patch-it tests the fix); (3) **proof** ("8 pull requests merged by outside maintainers", no other counts); (4) **layers covered**, as a table with two status columns, **Noticed** (a plugin watches it) and **Fixed** (patch-it writes the PR), each `live`, `in testing`, `building` or `planned`, never ahead of the truth; (5) **how to start** (a link to docs.patch-it.dev). |
| 6 | **Quickstart** (three or four steps, one screen) | The shortest path from a clean clone to the repo's main job, each step a command that runs as written, with the output to expect. Details live in linked docs. |
| 7 | **How it works, and links** | A short "how it works", the layout if the repo has code, how to run its checks, releases, contributing (with Discussions and good first issues), license, and docs.patch-it.dev. |
| 1 | **What** (two lines at most, bold first sentence, under the title) | What *this repo* is, in the product's words. For a part of patch-it, say which part of the story it is ("how patch-it notices, on its own, that something changed"). |
| 2 | **Badges** (one line of them) | The badge set below, in that order. |
| 3 | **Quickstart** (three steps) | The shortest path from a clean clone to the repo's main job, each step a command that runs as written. |
| 4 | **Links** | `docs/` pages (how-to, how it works), CONTRIBUTING, AGENTS, Discussions, good first issues, license, docs.patch-it.dev. |

**Never a list of what's covered** (providers, plugins, layers with statuses, counts): those change at run time and the code is their only source. Say how to find them (the docs site, `make plugins`) instead.

## The badge set

Expand Down Expand Up @@ -48,52 +49,17 @@ Use only images that are already public, linked by URL, never copied in: Patchy

# <repo>

**<What this repo is, in one line.>**

**Why:** when anything your code depends on changes (APIs, packages, SDKs, runtimes, CI, AI models), [patch-it](https://patch-it.dev) finds the code that breaks and opens the pull request that fixes it. In your CI, on your key. You get the fix, not the alert. <Why this repo matters to that.>
**<What this repo is, in one line.>** <One more line at most.>

<badges, in the order above>

```mermaid
flowchart LR
A["A dependency changes"] --> B["<this repo's part>"] --> C["Pull request in your repo"]
```

## What patch-it does

1. **It notices on its own.** ...
2. **It writes the fix.** ...
3. **Proof:** 8 pull requests opened by the early version have been merged by outside maintainers.
4. **What it covers:**

| Layer | Noticed | Fixed |
|---|---|---|
| APIs | live | live |
| AI models | live | live |
| Packages and SDKs | live | in testing |
| Runtimes | live | building |
| CI | live | planned |
## <Quickstart: the repo's main job in three steps>

5. **Start:** [docs.patch-it.dev](https://docs.patch-it.dev).
1. ...
2. ...
3. ...

## <Quickstart: the repo's main job in three or four steps>
## More

## How it works

## Contributing

## License
- <links to docs/, CONTRIBUTING, AGENTS, Discussions, license, docs.patch-it.dev>
````

Keep the layer statuses the same in every repo, and change them everywhere at once when one moves.

## When a repo goes public

The README is half of it. The same day, in the repo's settings:

1. **Description**: one line in the same words (what the repo is, the layers, "You get the fix, not the alert"), under 350 characters, no version-bot names, never API-only.
2. **Website**: `https://docs.patch-it.dev` (or the page in the docs about this repo).
3. **Topics**: from `dependencies`, `breaking-changes`, `api-changes`, `api`, `sdk`, `ai-models`, `ci`, `pull-requests`, `automation`, plus the repo's language and what it is (`go`, `plugins`, `documentation`, …).
4. **Discussions** on, if people will ask questions there; keep the categories Q&A, Ideas, Show and tell and Announcements.
5. **Social preview** (Settings → General → Social preview; GitHub has no API for it): a 1280×640 PNG, dark background from the brand tokens, the plain wordmark, Patchy on a cream tile, IBM Plex, the repo's one line. No gradients or glows.
6. Check a shared link to the repo shows its own card.
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
| Page | What's in it |
|---|---|
| [plugins.schema.json](plugins.schema.json) | The shape of `plugins.json`, the list of providers and sources that `go run ./cmd/list-plugins` prints from the registry and each release attaches. No list is committed. |
| [how-it-works.md](how-it-works.md) | Providers, sources and kinds; what a plugin does, version by version; the layout, the checks, releases. |
| [README-template.md](README-template.md) | The shape every public patch-it repo's README follows: sections, badge set, words, images. |
| [writing-a-plugin.md](writing-a-plugin.md) | How to add a provider: the `Plugin` interface, fetching through `env.Get` and `kit/`, saving the source, the golden test with `kittest`, the provider page and the source's metadata in its registration. |

Expand Down
Loading
Loading