Skip to content

changelog: SDK changelogs and release notes for Stripe, Sentry, Cloudflare, Octokit, ioredis, posthog-go - #232

Open
adssib wants to merge 17 commits into
mainfrom
pl4-changelog-all
Open

adssib wants to merge 17 commits into
mainfrom
pl4-changelog-all

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Combined PR for the stacked changelog work: #227 (reader) → #228 (Stripe) → #229 (Sentry) → #230 (Cloudflare) → #231 (Octokit, ioredis, posthog-go). Same commits; merge this one or the stack.

What this changes

Builds every high and medium changelog / migrationguide candidate of the source audit (2026-11-20) that the changelog reader can read with precision. 19 new sources, all versioned (every release from PyPI, npm, the repo's tags or its GitHub releases; no pins), each with a golden on a real consecutive pair and a drop test.

Source Packages Read from Golden pair (events)
stripe/python pypi:stripe stripe/stripe-python CHANGELOG.md 3.5.0→4.0.0 (4)
stripe/node npm:stripe stripe/stripe-node CHANGELOG.md 9.16.0→10.0.0 (8)
stripe/go go:github.com/stripe/stripe-go/v87 stripe/stripe-go CHANGELOG.md 72.122.0→73.0.0 (38)
stripe/java maven:com.stripe:stripe-java stripe/stripe-java CHANGELOG.md 20.136.0→21.0.0 (8)
stripe/ruby rubygems:stripe stripe/stripe-ruby CHANGELOG.md 6.5.0→7.0.0 (5)
stripe/dotnet nuget:Stripe.net stripe/stripe-dotnet CHANGELOG.md 39.126.0→40.0.0 (5)
stripe/php packagist:stripe/stripe-php stripe/stripe-php CHANGELOG.md 8.12.1→9.0.0 (13)
sentry/python-changelog pypi:sentry-sdk getsentry/sentry-python CHANGELOG.md 1.45.1→2.0.0 (8)
sentry/javascript-changelog npm:@sentry/node, npm:@sentry/browser getsentry/sentry-javascript CHANGELOG.md 9.47.2→10.0.0 (2)
sentry/go go:github.com/getsentry/sentry-go getsentry/sentry-go CHANGELOG.md 0.30.0→0.31.0 (1)
sentry/dotnet nuget:Sentry getsentry/sentry-dotnet CHANGELOG.md 3.41.4→4.0.0 (2)
cloudflare/typescript npm:cloudflare cloudflare/cloudflare-typescript CHANGELOG.md 7.0.0→7.1.0 (1)
cloudflare/python pypi:cloudflare cloudflare/cloudflare-python CHANGELOG.md 5.5.0→5.6.0 (7)
cloudflare/go go:github.com/cloudflare/cloudflare-go/v7 cloudflare/cloudflare-go CHANGELOG.md 7.14.0→7.15.0 (1)
cloudflare/terraform (terraform, not a package ecosystem) cloudflare/terraform-provider-cloudflare CHANGELOG.md 5.28.1→5.29.0 (1)
github/octokit-rest npm:@octokit/rest octokit/rest.js GitHub release notes 17.11.2→18.0.0 (155)
github/octokit-net nuget:Octokit octokit/octokit.net GitHub release notes 0.5.1→0.5.2 (1)
redis/ioredis npm:ioredis redis/ioredis CHANGELOG.md 4.31.0→5.0.0 (1)
posthog/go go:github.com/posthog/posthog-go PostHog/posthog-go CHANGELOG.md 1.44.1→2.0.0 (1)

Reader changes (#227): SDK changelog shapes in the classifier, Notes (GitHub release notes as the changelog; 12 candidates have only release notes), versions from tags for ecosystems with no registry lister, Go module named at its major.

Skipped, and why (precision over recall)

Changelog read, but no bullet in the whole history names a removal plainly (checked over every release section at HEAD; the reader would emit nothing): openai/python, openai/node, openai/go, openai/java, openai/dotnet (only in betas), openai/agents-python, anthropic/python, anthropic/typescript, anthropic/go, anthropic/java, anthropic/agent-sdk-python, anthropic/agent-sdk-typescript, google/genai-python, google/genai-js, google/genai-go, google/genai-java, google/aiplatform-python, algolia/python, algolia/js, algolia/instantsearch, appwrite/node, appwrite/python, appwrite/web, appwrite/cli, cloudflare/wrangler, convex/js, datadog/api-client-python, datadog/api-client-go, datadog/ddtrace-rb, datadog/terraform, elastic/go, elastic/terraform, flagsmith/python, flagsmith/js, flagsmith/nodejs, mongodb/node-changelog, mongodb/terraform, neon/serverless, neon/terraform (only in betas), newrelic/go-agent, newrelic/ruby-agent, newrelic/terraform, posthog/python, posthog/js, posthog/node, redis/go-redis, salesforce/cli, sentry/java, sentry/php, sentry/cli, supabase/js, supabase/python, vercel/ai-sdk, vercel/cli. Their breaking notes are prose ("breaking change to Decisions types", "Default API version is now v1", "Remove deprecated Projects endpoints") or name parameters, options and behavior.

Changelog the reader can't place at a release's tag: datadog/ddtrace-python (CHANGELOG.md is written on main after the release: the file at the release tag has no section for it), datadog/agent, mongodb/pymongo-changelog, newrelic/node-agent, newrelic/java-agent, redis/lettuce, redis/redis-rb (headings in shapes the reader doesn't parse, or a file with only the current release).

GitHub release notes, read with the new reader, no plain removal: redis/redis-py, github/octokit-js, github/terraform, datadog/ddtrace-java, redis/jedis, mongodb/go, mongodb/csharp, planetscale/database-js, vercel/sdk, supabase/cli.

Needs a reader that doesn't exist (fewer than 5 share it): docs release-notes pages elastic/python, elastic/java, stripe/api-changelog; GitLab-hosted gitlab/client-go, gitlab/terraform; RSS item per release newrelic/python-agent-notes (3 candidates).

Migration guides — none built: sentry/python (its 2.0 Removed/Deprecated lists are the CHANGELOG 2.0.0 section's: sentry/python-changelog already emits them; a second source would duplicate events under another id); sentry/javascript, datadog/ddtrace-js, datadog/ddtrace-go, datadog/datadog-ci, redis/node-redis, cloudflare/terraform-upgrade (prose sections about options, env vars and behavior; a heading reader found 0–2 symbols each); openai/node-migration (a generic reader emits false positives: "Removed request options overloads" lists methods that still exist); anthropic/typescript-migration (the file is a stub); supabase/flutter (pub is not a registry ecosystem; prose); HTML guides with no reader: algolia/python-upgrade, algolia/js-upgrade, mongodb/pymongo, mongodb/node, mongodb/server-compat, elastic/elasticsearch-breaking, elastic/js, vercel/ai-sdk-migration, posthog/sdk-majors. The existing migrationguide readers (removed-parameter tables, removed-member tables) fit none of them.

Checklist

  • Metadata complete in the registration, and I read the words
  • Every commit is signed off (DCO)
  • Golden test over a real saved copy for each source (testdata/golden/<provider>-<source>.json)
  • testdata/README.md lists each file: URL, tag commit, date, license, quote
  • One pinned drop test per source
  • Provider pages with Why this source: stripe-sdks.md, sentry-sdks.md, cloudflare-sdks.md, github-octokit.md, redis-ioredis.md, posthog-go.md
  • Fetches only through env.Get
  • make check passes on every branch of the stack
  • Nothing private

Review round 1 (fixed)

  • Renames are followed to their end within a release (replaceLabels → setLabels; a chain ending in a removal is a removal), with a unit test for a two-step chain, a chain ending in a removal and a loop.
  • Names alone are a removal only under a Removed heading (not under "Breaking Changes" / "Major Changes"), and a change word (Deprecated:, Added:) is never read past as an area. This removed false positives in the old cloudflare/typescript 7.2.0 golden (methods listed under "Empty body params removed" still exist): it now pins 7.1.0's plain rename. octokit-net's 0.19.0 event was the same shape: it now pins 0.5.2 (MilestoneUpdate.Number is now removed).

Release

New exported API in plugins/changelog (File.Notes, File.Cite, NotesSections, the SDK File vars) → a minor release, not the automatic patch.

Calls I made (please check)

  • plugin.Version.MapsTo (plugin: a version can say which version of another source it pins #226) isn't merged yet, so it isn't filled here. The seven Stripe SDK sources can fill it from their own changelogs ("This release changes the pinned API version to 2026-11-18.endive") once it lands.

  • Source ids follow the audit (sentry/python-changelog, sentry/javascript-changelog), since sentry/python / sentry/javascript were proposed for the migration guides.

  • go: packages list the module path the audit verified (current major); events name the module at each release's major (/v73).

  • Terraform providers have no Packages entry (no terraform ecosystem in plugin.Ecosystems()); events carry ecosystem terraform.

  • Testdata is trimmed to two release sections per changelog (golden + drop test), each unchanged.

  • Bullets that remove webhook event names or span attribute names (Stripe order.payment_failed, Sentry gen_ai.system) are read as removed names: they're strings code uses.

Refs #185, #186, #188, #194, #202, #203, #204, #35, #36, #37.

🤖 Generated with Claude Code

adssib and others added 5 commits November 20, 2026 21:04
The classifier reads the SDK changelogs' shapes: release-please's
"⚠ BREAKING CHANGES", changesets' "Major Changes", Stripe's ⚠️ bullets,
"**[BREAKING]**" and "feat!:" marks, an area, issue or commit a bullet
starts with, passive removals and renames from an owner, and semantic-
release's "# [X.0.0]" major headings. A File can read each GitHub
release's notes (Notes), list releases from the repo's tags for an
ecosystem with no registry lister, and names a Go module at its major.

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

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 22s —— View job


⚠️ Merge after fixes. The reader, the registrations and the tests are in good shape. One precision bug in the Octokit release notes would send users to method names that v18 removed.

Rules

Rule Status Evidence
Plugin list (metadata in the registration) ✅ Each provider uses plugin.RegisterProvider with id, name, category and homepage. Every source goes through sdk() (plugins/changelog/sdks.go), which fills in id, layer, page, what it watches, URLs and packages. Terraform sources get LayerInfra. No hand-kept list was added.
Provider page ✅ 6 new pages (stripe-sdks.md, sentry-sdks.md, cloudflare-sdks.md, github-octokit.md, redis-ioredis.md, posthog-go.md). Each has Why this source with a link, the date checked (2026-11-20), alternatives and a quote.
Golden test and quote ✅ (with the bug below) 19 goldens over saved copies at the tags. testdata/README.md has a row for each file. Every event carries source_url (the file at its tag, or the release page) and source_excerpt.
Drop test ✅ One pinned drop test per source in *_test.go
Fetch only via env ✅ No net/http. Fetches go through env.Get and core/versions (GitHubReleases, GitHubTags).
Nothing private ✅ Leak guard is clean, and I read the PR body and the commit subjects.
No golden edited ✅ All the golden files are new.

Bugs

  1. Chained renames point to names that were removed (plugins/changelog/changelog.go:329, inline comment). The octokit/rest v18.0.0 notes rename A→B and, in the same release, rename or remove B. Each bullet becomes its own event, so github-octokit-rest.json tells users to switch:

    • issues.replaceLabels → replaceAllLabels, which is itself renamed to setLabels
    • actions.listWorkflowJobLogs → downloadWorkflowJobLogs, which is itself renamed
    • reactions.delete → deleteLegacy, which this release removes

    A wrong replacement becomes a wrong PR in someone's repo. To fix it, follow each replacement through the release's other renames and removals before emitting the event: use the end of the chain, or drop the replacement if the chain ends in a removal. Then regenerate the golden.

Verified

  • go build ./...: passes
  • go vet ./...: passes
  • gofmt -l .: prints nothing
  • go test -race ./...: all packages pass, including plugins/changelog
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • Read the reader diff (changelog.go, classify.go, parse.go), the Stripe registration and its page, and the octokit-rest saved release and golden.
  • I didn't run make check (this runner needs approval for it). I ran its main steps one by one, as listed above.

Non-blocking

  • noisePrefix (classify.go) strips any leading Word: . If a bullet under a Breaking heading says "Deprecated: foo" or "Added: Foo type", the prefix is stripped and the bare template then reads the bullet as a removal. None of the goldens hits this today. You could keep a list of known area labels, or skip stripping when the word is a change verb (Added, Changed, Deprecated, Fixed).
  • Treating changesets' "Major Changes" as breaking makes bare (names only, no verb) count as a removal in that section too. Under a "Removed" heading that's right; under "Major Changes" it's less certain. You could limit bare to sections whose title says removed.
  • The changelog bullets look duplicated in places. Only the parameter-rename bullets (dropped anyway) are actually listed twice, and the new fingerprint dedupe handles those.

now := env.Now().UTC()
var events []event.Event
var rejected []error
seen := map[string]bool{} // a changelog that lists a bullet twice is one change

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chained renames produce replacements that no longer exist. The octokit/rest v18.0.0 notes list both halves of several chains, and each bullet becomes its own event, so the golden tells users to migrate to names that v18 removed:

  • octokit.issues.replaceLabels → replacement octokit.issues.replaceAllLabels, but replaceAllLabels is itself "renamed to octokit.issues.setLabels()"
  • octokit.actions.listWorkflowJobLogs → downloadWorkflowJobLogs, which is itself renamed to downloadJobLogsForWorkflowRun
  • octokit.reactions.delete → deleteLegacy, which this same release removes ("deprecated octokit.reactions.deleteLegacy() has been removed")

A codemod that follows these replacements turns working v17 code into code that breaks on v18. Since you already loop over the release's findings here, one fix is to collect the release's renamed and removed symbols first, then rewrite each Replacement by following the chain to its end (replaceLabels → setLabels). If the chain ends in a removal, drop the replacement (or the event). Please regenerate github-octokit-rest.json afterwards, and add a unit test that covers a two-step chain and a chain that ends in a removal.

adssib and others added 6 commits November 20, 2026 21:15
A rename whose new name the same release renames again or removes now
points to where the chain ends (or to nothing). A bullet of names alone
is a removal only under a Removed heading, and a change word
("Deprecated:") is never read past as an area.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
7.2.0's events came from bare names under a heading about removed body
params: the methods still exist. With names alone read only under a
Removed heading, 7.2.0 has no event; 7.1.0's rename is the golden.

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

adssib commented Nov 21, 2026

Copy link
Copy Markdown
Contributor Author

@claude review

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 58s —— View job


✅ Ready to merge. Both round 1 fixes are in and pinned by tests, and the reader is stricter than it was. I found no blocking bugs in this round.

  • Read the round 1 fixes (rename chains, bare only under Removed, change words)
  • Check the registrations, pages, goldens, testdata README and drop tests against AGENTS.md
  • Look for precision problems in the goldens
  • Post the verdict

Rules

Rule Status Evidence
Metadata in the registration ✅ Each provider (stripe, sentry, cloudflare, github, redis, posthog) calls plugin.RegisterProvider with id, name, category and homepage. These match the existing registrations of the same ids in notices, openapi, catalog and migrationguide. Every source goes through sdk() (plugins/changelog/sdks.go:11), which fills in id, layer (LayerInfra for Terraform), page, what it watches, URLs and packages. No hand-kept list. The doc edits in AGENTS.md, which-kind.md and writing-a-plugin.md only describe the new Notes shape.
Provider page ✅ 6 pages. Each has Why this source with a link, the date checked (2026-11-20), why it's the best source, the alternatives and a quote. github-octokit.md now also explains the rename chains.
Golden, quote, drop test ✅ 19 goldens over saved copies at the tags, a testdata/README.md row for each, and one pinned drop test per source (checkSDKs cases). Every event carries source_url (the file at its tag, or the release page through Cite()) and a source_excerpt. The two re-pinned goldens (cloudflare/typescript 7.1.0, octokit-net 0.5.2) are explained in the PR body.
Fetch only via env ✅ No net/http. Fetches go through env.Get and core/versions (GitHubReleases, GitHubTags). No filesystem access outside testdata/.
Precision over recall ✅ See below.
Nothing private ✅ I read the PR body, the commit subjects, the pages and the testdata rows. I found no internal names, credentials or private links.

Round 1 fixes, checked

  • Rename chains (changelog.go:200, chained): in github-octokit-rest.json, issues.replaceLabels → issues.setLabels and actions.listWorkflowJobLogs → downloadJobLogsForWorkflowRun. reactions.delete is now a plain removal, because deleteLegacy is removed in the same release. No replacement in the golden points to a name the release removes. TestRenamesAreFollowedToTheirEnd covers a two-step chain, a chain that ends in a removal, and a loop.
  • Names alone are a removal only under a Removed heading: KindRemoved is a new kind, and bare is gated on removedHeading. Breaking, Major Changes and ⚠️ sections no longer turn a bare list of names into removals.
  • Change words are not read past as areas: changeWord stops noisePrefix from stripping Deprecated: or Added:. As a result, "Deprecated: X" under a Breaking heading is now dropped instead of read as a removal.

Non-blocking suggestions

  1. The migration hint still names the middle of the chain. For replaceLabels, the description says "renamed to setLabels", but migration_hint quotes the bullet "renamed to replaceAllLabels()". The quote is correct as provenance. A tool that only shows the hint, though, would send users to the intermediate name. You could append "(renamed again in this release: use octokit.issues.setLabels)" when chained rewrites a replacement.
  2. chained also rewrites deprecations (changelog.go:214). The rewrite loop skips only dropped findings. Take "Deprecated X in favor of Y" in a release that also removes Y: the finding keeps ChangeTypeDeprecation but gets Change = PackageRemovedSymbol, which says X was removed. No golden has this case. You could limit the rewrite to ChangeTypeBreaking, or drop only the replacement on a deprecation.
  3. "Removed:" and "Renamed:" are read past as area labels, because noisePrefix matches [A-Z][a-zA-Z]+: and changeWord doesn't list them. Under a Removed heading, the names still count, so nothing is lost there. Under a Breaking heading, "Removed: X" is dropped. That loses recall, not precision. Adding removed|renamed to changeWord would only help if a template then accepts "Removed: §", so this is fine to leave as is.
  4. Release notes can be edited after the release (already listed under Known gaps in github-octokit.md). A later edit that adds a bullet produces an event at a later run. It can't produce one for a non-change, so this is just a note.

I can't run the tests from here. CI_go runs them (make check: build, vet, gofmt, imports, the net/http guard, go test -race, todos and the leak guard).

The PR body is right that new exported API (File.Notes, File.Cite, NotesSections) calls for a minor release. That is the maintainer's call when they run Release.

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