Skip to content

add the sentry plugin - #130

Merged
brandonphelps1212 merged 3 commits into
mainfrom
sentry-plugin
Nov 19, 2026
Merged

brandonphelps1212 merged 3 commits into
mainfrom
sentry-plugin

Conversation

@brandonphelps1212

Copy link
Copy Markdown
Contributor

What this changes

Adds sentry on the openapi format plugin. Part of #78 (I12.1 · Watch Sentry), under #15.

  • Source: Sentry's OpenAPI spec, openapi-derefed.json.
    • Now: an asset on each [email protected] release of getsentry/sentry. LatestTag takes the highest api@ version, skipping drafts, prereleases and releases without the spec.
    • History: getsentry/sentry-api-schema (archived 2026-11-14, "@sentry/api has moved"). Fetch also takes a tag of that repo or a full commit SHA there, so its history can be replayed.
  • version is the release's date, or the commit's committer date. The API has no version ("v0").
  • New diff.Options.DeprecatedDescription: an operation deprecated in words in its description. Sentry mostly deprecates that way: the flag alone catches 3 of its 13 deprecations, and late (user-feedback was deprecated in words on 2024-07-31 and flagged about 23 months later). A nil value changes nothing for any other plugin.
    • Sentry's matcher accepts:
      • a ## Deprecated heading alone on its line (## Deprecated 🚧 too);
      • **Deprecated**: or **Deprecated:** at a line's start;
      • "This endpoint is deprecated", in any case.
    • It rejects "deprecat" anywhere, which would match "Eventsv2 Deprecation Note" and "deprecation details", and it rejects ## Deprecated fields.
  • Base path: on 2026-11-13 the spec moved /api/0 from the paths into the server URL, which reads as 289 operations removed and 289 added. Fetch moves it back into the path keys, so operations are named as callers send them (GET /api/0/...) across the whole history. A Reshaper maps each event's pointer back to the published file.
  • Keep: operation deprecations only, no removals. Leaving Sentry's spec means Sentry stopped documenting an operation, and the history doesn't show when, or whether, it stopped working. Of the 11 removed operations that had been deprecated, stats/ is still routed today.
  • History (1,130 spec commits since 2020 plus 19 api@ releases): 13 deprecations, none withdrawn: stats/ (2022-03-01), user-feedback (2024-07-31), issues (2025-07-25), and the 10 alert-rules operations (2026-01-22).

Checklist

  • Added to docs/plugins.md: new row (Layer API, status live), docs/plugins.json regenerated, README badge now 23 (after add the posthog plugin #129). I compared the registered plugins with the table.
  • Every commit is signed off (DCO)
  • Golden test over trimmed real copies: three commit pairs, giving 12 events (user-feedback, issues, and the 10 alert-rules operations).
  • testdata/README.md rows: URL at the commit or tag, date, quote. License: FSL-1.1-Apache-2.0 for copies after 2026-02-10. Earlier copies predate the repo's license file, so they carry only the spec's own info.license, Apache 2.0.
  • Pinned drop test: 2.0.1 → 2.1.0, the base-path move, gives no event. As published, the same pair reports all 5 saved operations removed.
    • Also: 0.223.0 → 0.224.0 (the flag on two operations already deprecated in words) gives no event; the flag alone would give 2.
    • Also: the three "deprecat" descriptions that aren't deprecations give no event.
  • providers/sentry.md from the template, including Why this source.
  • Fetches only through the shared fetch layer under adapter/.
  • make check passes.
  • Nothing private.

Notes for the reviewer

  • Client side: version is a date, so the patch-it client's DATE_VERSIONED_APIS needs sentry. That's a one-line PR in patch-it, opened alongside this one.
  • A release asset is pinned only by its tag. GitHub lets maintainers replace an asset, so this is a weaker pin than a commit. The provider page says so.
  • The reshaped spec is stored compact (16.7 MB published, about 6.5 MB as stored), so the baseline isn't the published bytes. Events cite the published file, and the pointers are checked against it.
  • Known gaps (on the provider page): no removals; deprecations said another way ("has been replaced"); a deprecation reported twice if its words are removed and put back.
  • An independent review reran the matcher over all 1,130 spec commits and all 19 releases. It found exactly the 13, and no wrong event. It replayed real pairs end to end against GitHub, with every pointer resolving to its excerpt. Its fixes are included: the tighter heading pattern, **Deprecated:**, the license column, and two inaccurate notes.

🤖 Generated with Claude Code

brandonphelps1212 and others added 3 commits November 19, 2026 17:16
Watch Sentry's public REST API spec (openapi-derefed.json, an asset of
each [email protected] release of getsentry/sentry; before 2026-11-14, files at
getsentry/sentry-api-schema tags and commits) for operation deprecations.

- diff: Options.DeprecatedDescription reads a deprecation from an
  operation's description and cites the description. Nil (every other
  plugin) changes nothing.
- adapter.Sentry: the highest api@ release, dated by its publication;
  /api/0 moved from the server URL back into every path, so the
  2026-11-13 base-path move isn't 289 removals, with source pointers
  mapped back to the published file (Reshaper).
- Keep: deprecations only. Over the whole history, 13 events, 3 by the
  flag alone; no removals (see providers/sentry.md).

The version is a date: the patch-it client's date-versioned APIs need
sentry. docs/plugins.md has its row, checked against the registry.

Signed-off-by: brandonphelps1212 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…rate notes

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
@claude

claude Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Claude finished @brandonphelps1212's task in 1m 28s —— View job


✅ Ready to merge: every repo rule is met, the new code is careful about precision, and build, vet, gofmt, tests and the leak guard all pass locally.

Rules

Rule Status Evidence
Plugin list (Rule 1) ✅ New sentry row in docs/plugins.md between the markers: plain table, absolute links. I checked its id, provider, layer, what it watches, format (openapi), source and status live against plugins/openapi/openapi.go:48 and adapter/sentry.go, and they match. docs/plugins.json is regenerated, the badge is 23, and internal/pluginlist tests pass.
Provider page ✅ providers/sentry.md follows the template. Why this source has the link, the date checked (2026-11-19), why this source, three alternatives it doesn't use (changelog, SDK changelogs, urls.py) and a quote. It's also listed in providers/README.md.
Golden test + quote ✅ testdata/golden/sentry.json comes from three real commit pairs and gives 12 events. Each copy has a testdata/README.md row with URL, date, license and quote. The trimming is described too. Events cite the published file, and SourcePointer maps the pointers back to it.
Drop test ✅ Pinned: 2.0.1 → 2.1.0 (the /api/0 move) gives no event. There are more no-event cases: the flag added after the words, and the two descriptions that use "deprecation" without deprecating anything.
Fetch only via env/kit ✅ Network access is only through fetch.Get in adapter/ (no net/http, no filesystem, no database).
Nothing private (Rule 2) ✅ No credentials, internal names, private links or session links in the code, tests, docs or PR text. leak_guard.py --all is clean.
Contract ✅ contract/fixtures/ isn't touched.

Bugs

None found. Things I checked in particular:

  • diff.Options.DeprecatedDescription: when it's nil, descriptionDeprecated returns false, so the other plugins behave exactly as before. The new case d.opts.summaryDeprecated(newOp) keeps the old summary branch unchanged. The default is now reached only when the description matched, so it never cites the wrong field.
  • Precision of the matcher (plugins/openapi/sentry.go:460): it's anchored to a heading alone on its line, **Deprecated**: / **Deprecated:** at a line's start, or the full phrase "this endpoint is deprecated". So "Eventsv2 Deprecation Note", "deprecation details" and ## Deprecated fields don't match. The no-event tests confirm it.
  • sentryKeep keeps OperationDeprecated only. A spec without its base path compared to one with it can't produce a removal event. And because both sides go through sentryBasePath, mixing old commits with new api@ releases gives no flood of removals and re-additions.
  • SourcePointer only rewrites pointers under /paths/<base>~1…, and only for content that carries the x-patch-it-base-path key. Specs that weren't changed come back byte for byte.

Verified

  • go build ./...: OK
  • go vet ./...: no output
  • gofmt -l .: no output
  • go test -race ./...: all packages pass, plugins/openapi, adapter and diff included
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"

Non-blocking (optional)

  • LatestTag reads only the first page of /releases?per_page=100. getsentry/sentry also publishes server and npm releases there. If 100 of those ever came after the last api@ release, it would fail with "no api@ release" (an error, not a wrong event). With api@ releasing several times a day that's unlikely, so I'd leave it unless it happens.
  • Remember the companion patch-it PR adding sentry to DATE_VERSIONED_APIS. Until that lands, the client will drop these events, as the PR notes.

Thanks for the history replay and the careful notes on the provider page. They made this easy to check.

@brandonphelps1212
brandonphelps1212 merged commit 0afe2bc into main Nov 19, 2026
5 checks passed
@brandonphelps1212
brandonphelps1212 deleted the sentry-plugin branch November 19, 2026 22:43
@brandonphelps1212 brandonphelps1212 mentioned this pull request Nov 19, 2026
15 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant