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 @@ -58,9 +58,10 @@ core/event/ core/migrate/ the change-event types from patch-it's contract (
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, feed, apichangelog, catalog, eol;
members/), changelog (Markdown, RST or JSON), feed, catalog, eol;
plugins/all imports every one
plugins/removedmembers/ deprecated: merged into migrationguide, only forwards there
plugins/removedmembers/ plugins/apichangelog/ deprecated: merged into migrationguide and
changelog, 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
8 changes: 4 additions & 4 deletions cmd/new-plugin/formats.go
Original file line number Diff line number Diff line change
Expand Up @@ -341,15 +341,15 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 {
},

"apichangelog": {
kind: "apichangelog",
kind: "changelog",
layer: "api",
defDir: "plugins/apichangelog",
def: `package apichangelog
defDir: "plugins/changelog",
def: `package changelog

// {{.Ident}} is {{.Provider}}'s machine-readable API changelog.
//
// ` + todo + `: the repo and the file's path, and what you checked, with the
// date, as apichangelog.go does for MongoDB Atlas.
// date, as json.go does for MongoDB Atlas.
var {{.Ident}} = Log{
API: "{{.ID}}", Vendor: "{{.Provider}}", Name: "TODO: the API's name, for sentences",
Repo: "TODO-owner/TODO-repo", Path: "changelog/changelog.json",
Expand Down
1 change: 1 addition & 0 deletions core/plugin/provider.go
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,7 @@ func KindOf(p Plugin) string {
// they read is read by the new kind, with the same events.
var mergedKinds = map[string]string{
"removedmembers": "migrationguide",
"apichangelog": "changelog",
}

// CanonicalKind is the kind name means now: name itself, or, for a kind
Expand Down
2 changes: 1 addition & 1 deletion docs/how-it-works.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ There's no list in this repo: `make plugins` prints every provider and source fr
| [`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 |
| [`contract/fixtures/`](../contract/) | A copy of patch-it's change-event fixtures |
| `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 |
| `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 |
| [`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", "apichangelog", "catalog", "eol"] },
"kind": { "type": "string", "enum": ["openapi", "retirements", "migrationguide", "changelog", "feed", "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 (a migrationguide source), changelog, feed, apichangelog, catalog
# --format: openapi, retirements, migrationguide, removedmembers (a migrationguide source), changelog, feed, 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/)
```
Expand Down Expand Up @@ -77,10 +77,9 @@ 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` | 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/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/apichangelog` | A vendor's machine-readable API changelog in JSON (per day, endpoint and API version, oasdiff change codes), at the commit that last changed it | An `apichangelog.Log` |
| `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
1 change: 0 additions & 1 deletion plugins/all/all.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
package all

import (
_ "github.com/patch-it-dev/patch-it-plugins/plugins/apichangelog"
_ "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"
Expand Down
288 changes: 12 additions & 276 deletions plugins/apichangelog/apichangelog.go
Original file line number Diff line number Diff line change
@@ -1,282 +1,18 @@
// Package apichangelog is the source plugin for a vendor's machine-readable
// API changelog: a JSON file, kept in a repo, that lists per day each
// endpoint's changes per API version, each with a change code (oasdiff's) and
// whether it's backward compatible. MongoDB publishes one for the Atlas
// Administration API.
// Package apichangelog is the old import path of the changelog kind's JSON
// parser, kept so code that imports it still builds.
//
// It reads only an endpoint's life cycle, in the vendor's own words: an API
// version deprecated (`deprecation`), unless the vendor reactivates it later,
// and an API version removed at its sunset (`breaking`). The rest of the changelog is property-level, and the vendor's
// "not backward compatible" there is broad (a response enum gaining a value
// counts), so it isn't read: precision over recall.
//
// The file is read at the commit that last changed it, whose URL never
// changes, so that URL is the events' provenance (no snapshot). Every run
// reads the whole file; the fingerprints dedupe.
// Deprecated: use plugins/changelog: Plugin{Log: changelog.MongoDBAtlas}.
// This package only forwards there and registers nothing; it goes once
// nothing imports it.
package apichangelog

import (
"bytes"
"context"
"encoding/json"
"fmt"
"log"
"sort"
import "github.com/patch-it-dev/patch-it-plugins/plugins/changelog"

"github.com/patch-it-dev/patch-it-plugins/core/event"
"github.com/patch-it-dev/patch-it-plugins/core/github"
"github.com/patch-it-dev/patch-it-plugins/core/kit"
"github.com/patch-it-dev/patch-it-plugins/core/plugin"
type (
// Plugin is changelog.Plugin: set Log, as before.
Plugin = changelog.Plugin
Log = changelog.Log
Finding = changelog.LogFinding
)

func init() {
plugin.RegisterProvider(plugin.Provider{
ID: "mongodb", Name: "MongoDB", Category: plugin.CategoryDatabases, Homepage: "https://www.mongodb.com",
Sources: []plugin.Source{{
ID: "atlas-admin-api", Layer: plugin.LayerAPI, Page: "providers/mongodb-atlas.md",
Watches: "Atlas Administration API versions deprecated and removed at their sunset date, per endpoint, from MongoDB's own API changelog",
URLs: []string{"https://github.com/mongodb/openapi/blob/main/changelog/changelog.json"},
Plugin: Plugin{Log: MongoDBAtlas},
}},
})
}

// Log is one vendor's changelog file.
type Log struct {
API string // the events' api: "mongodb-atlas"
Vendor string // for sentences: "MongoDB"
Name string // the API, for sentences: "Atlas Administration API"
Repo string // owner/name on GitHub
Path string // the file's path in the repo
}

// MongoDBAtlas is the Atlas Administration API's changelog,
// changelog/changelog.json in mongodb/openapi (checked 2026-11-19: 188 days
// from 2023-02-01 to 2026-11-18, released by MongoDB's CI, "Release API
// Changelog", a few times a month; the docs page
// https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/
// is built from it). Atlas versions each resource by date (`2023-01-01`),
// chosen per request in the Accept header.
var MongoDBAtlas = Log{
API: "mongodb-atlas", Vendor: "MongoDB", Name: "Atlas Administration API",
Repo: "mongodb/openapi", Path: "changelog/changelog.json",
}

// CommitsURL lists the newest commit that changed the file.
func (l Log) CommitsURL() string {
return fmt.Sprintf("https://api.github.com/repos/%s/commits?path=%s&per_page=1", l.Repo, l.Path)
}

// URL is the file at one commit: its own provenance.
func (l Log) URL(sha string) string {
return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", l.Repo, sha, l.Path)
}

// The file's shape: newest day first.
type day struct {
Date string `json:"date"`
Paths []struct {
Path string `json:"path"`
Method string `json:"httpMethod"`
Versions []struct {
Version string `json:"version"`
Changes []json.RawMessage `json:"changes"`
} `json:"versions"`
} `json:"paths"`
}

type change struct {
Change string `json:"change"`
ChangeCode string `json:"changeCode"`
BackwardCompatible bool `json:"backwardCompatible"`
}

// lifecycle is what each change code this plugin reads means, each about a
// whole endpoint at one API version: "endpoint deprecated"; "new resource
// added 2023-02-01. Resource version 2023-01-01 deprecated and marked for
// removal on 2025-06-01"; "endpoint with API Version '2023-01-01' was removed
// as it has reached its sunset date '2026-01-22'".
//
// Not read: "api path removed without deprecation". Its one entry
// (streams/activeVpcPeeringConnections, 2025-01-10) comes with
// `endpoint-added` the same day, and the endpoint changes again later: it
// wasn't removed.
var lifecycle = map[string]event.ChangeType{
"endpoint-deprecated": event.ChangeTypeDeprecation,
"resource-version-deprecated": event.ChangeTypeDeprecation,
"endpoint-removed": event.ChangeTypeBreaking,
}

// reactivated withdraws a deprecation: "endpoint reactivated". MongoDB does
// it (13 times by 2026-11-18): GET /api/atlas/v2/groups/{groupId}/clusters
// at 2024-05-30 was deprecated on 2024-06-25 and reactivated the next day.
const reactivated = "endpoint-reactivated"

// Finding is one life-cycle change.
type Finding struct {
ChangeType event.ChangeType
Date string // the changelog's day
Operation string // "GET /api/atlas/v2/groups/{groupId}/clusters"
Version string // the API version it's about: "2023-01-01"
Code string
Pointer string // RFC 6901, into the file
Excerpt string // the change, as JSON
}

// Read finds every life-cycle change in the file that still stands, by
// replaying the days oldest first: a reactivation of an endpoint's version
// withdraws its deprecation, and a deprecation after that is a new one. A
// deprecation counts from the first time it's announced since the last
// reactivation; the changelog repeats some. A removal counts from its first
// announcement too, and is withdrawn, with any deprecation before it, if the
// same endpoint and version shows up again on a later day with anything but
// another removal (none of the 38 in the file on 2026-11-18 does). The excerpt is the change as the file writes
// it, whitespace aside.
func (l Log) Read(b []byte) ([]Finding, error) {
var days []day
if err := json.Unmarshal(b, &days); err != nil {
return nil, fmt.Errorf("not a changelog: %w", err)
}
if len(days) == 0 {
return nil, fmt.Errorf("the changelog has no days: it may have moved or changed shape")
}
type item struct {
seq int
f Finding
}
deprecated := map[string]item{} // by operation and version, until reactivated
removed := map[string]item{}
seq := 0
for di := len(days) - 1; di >= 0; di-- {
d := days[di]
for pi, p := range d.Paths {
for vi, v := range p.Versions {
for ci, raw := range v.Changes {
var c change
if err := json.Unmarshal(raw, &c); err != nil {
return nil, fmt.Errorf("day %s, %s %s: %w", d.Date, p.Method, p.Path, err)
}
op := p.Method + " " + p.Path
key := op + " " + v.Version
if r, ok := removed[key]; ok && r.f.Date < d.Date && lifecycle[c.ChangeCode] != event.ChangeTypeBreaking {
// It came back. Whether its old deprecation still
// applies is unclear, so that goes too.
delete(removed, key)
delete(deprecated, key)
}
if c.ChangeCode == reactivated {
delete(deprecated, key)
continue
}
ct, ok := lifecycle[c.ChangeCode]
if !ok {
continue
}
var ex bytes.Buffer
if err := json.Compact(&ex, raw); err != nil {
return nil, err
}
f := Finding{
ChangeType: ct, Date: d.Date, Operation: op, Version: v.Version, Code: c.ChangeCode,
Pointer: fmt.Sprintf("/%d/paths/%d/versions/%d/changes/%d", di, pi, vi, ci),
Excerpt: ex.String(),
}
seq++
target := deprecated
if ct == event.ChangeTypeBreaking {
target = removed
}
if _, dup := target[key]; !dup {
target[key] = item{seq, f}
}
}
}
}
}
all := make([]item, 0, len(deprecated)+len(removed))
for _, it := range deprecated {
all = append(all, it)
}
for _, it := range removed {
all = append(all, it)
}
sort.Slice(all, func(i, j int) bool { return all[i].seq < all[j].seq })
out := make([]Finding, len(all))
for i, it := range all {
out[i] = it.f
}
return out, nil
}

// Plugin reads one vendor's changelog.
type Plugin struct {
Log Log
}

func (p Plugin) Name() string { return p.Log.API }

// Run reads the file at the newest commit that changed it.
func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) {
l := p.Log
sha, err := github.LatestCommit(ctx, env.Get, l.CommitsURL())
if err != nil {
return plugin.Result{}, fmt.Errorf("looking up %s's newest changelog commit (%s in %s): %w", l.API, l.Path, l.Repo, err)
}
url := l.URL(sha)
page, err := env.Get(ctx, url)
if err != nil {
return plugin.Result{}, fmt.Errorf("fetching %s: %w", url, err)
}
last, same, err := kit.Unchanged(env, l.API, page)
if err != nil {
return plugin.Result{}, err
}
if same {
log.Printf("%s: no change since %s", l.API, last.SourceURL)
return plugin.Result{}, nil
}
findings, err := l.Read(page)
if err != nil {
return plugin.Result{}, fmt.Errorf("reading %s: %w", url, err)
}

now := env.Now().UTC()
var events []event.EventV2
var rejected []error
for _, f := range findings {
e := event.EventV2{
API: l.API,
Version: f.Version,
ChangeType: f.ChangeType,
Breaking: f.ChangeType == event.ChangeTypeBreaking,
Subject: event.Subject{Type: event.SubjectAPIOperation, Kind: event.AffectedKindOperation, Side: event.SideRequest, Operation: f.Operation},
Description: describe(l, f),
SourceURL: url,
SourcePointer: f.Pointer,
SourceExcerpt: f.Excerpt,
Confidence: 1.0,
DetectedAt: now,
}
e.Fingerprint = event.FingerprintV2(e.API, e.Version, e.ChangeType, e.Subject, "")
if err := e.Validate(); err != nil {
rejected = append(rejected, fmt.Errorf("%s %s %s: %w", l.API, f.Operation, f.Version, err))
continue
}
events = append(events, e)
}
return plugin.Result{
Label: url,
Events: events,
Rejected: rejected,
Baselines: []plugin.Spec{plugin.Baseline(l.API, sha, sha, url, page, false, now)},
}, nil
}

func describe(l Log, f Finding) string {
switch f.ChangeType {
case event.ChangeTypeBreaking:
return fmt.Sprintf("%s %s, API version %s, removed on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code)
default:
return fmt.Sprintf("%s %s, API version %s, deprecated on %s (%s's changelog, %s).", l.Name, f.Operation, f.Version, f.Date, l.Vendor, f.Code)
}
}
var MongoDBAtlas = changelog.MongoDBAtlas
Loading
Loading