Skip to content

changelog: read SDK changelogs, release notes and tag-listed releases - #227

Open
adssib wants to merge 3 commits into
mainfrom
pl4-changelog-reader
Open

adssib wants to merge 3 commits into
mainfrom
pl4-changelog-reader

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

The changelog kind learns to read the official SDK changelogs the source audit lists, without new kinds:

  • Classifier (classify.go): release-please's ⚠ BREAKING CHANGES, changesets' Major Changes, Stripe's ⚠️ bullets, **[BREAKING]**, conventional-commit feat!: marks; an area, issue or commit a bullet starts with (**accounts:**, [#1914](...), fc05013:, Tracing - ) is read past; passive removals and renames from an owner (X has been removed from Y, X has been renamed to Y); Class#member read as Class.member. Still one plain sentence over code spans, or no event.
  • Headings (parse.go): Stripe's ## <a id="…"></a>X.Y.Z, Datadog's ## X.Y.Z/date, semantic-release's # [X.0.0](…) for a major (it used to fold a major into the patch above it); fenced code is never a title or a bullet.
  • Release notes (File.Notes): an SDK with no changelog file is read from each GitHub release's notes (/repos/{repo}/releases/tags/{tag}), cited by its release page; versions are the repo's published releases. Added because 12 audit candidates have only release notes (the rule: a shared reader once ≥5 need it).
  • Versions from tags: for an ecosystem with no registry lister (Go, Maven, NuGet, RubyGems, Packagist, Terraform), a File lists the repo's TagPrefix + X.Y.Z tags. No pinned tags.
  • Go modules: events name the module at the release's major (…/stripe-go/v73).
  • Duplicate bullets in one release give one event.

No source is added here; the stacked PRs register them.

Checklist

  • Metadata complete in the registration. Not applicable: no source added here (see the stacked PRs).
  • Every commit is signed off (git commit -s, DCO)
  • Golden test over a real saved copy of the source: the existing goldens (textual, urllib3, mongodb-atlas) are unchanged byte for byte
  • testdata/README.md lists each file (the two version-list fixtures, written for the test)
  • Drop test: n/a for the reader; unit cases pin what is dropped (**api:** add support for new API version … under ⚠ BREAKING CHANGES)
  • providers/…: n/a (no source)
  • Fetches only through env.Get
  • make check passes locally
  • Nothing private

Notes for the reviewer

  • Precision over recall: over the 88 SDK changelogs the audit lists (checked 2026-11-20), the reader finds plainly named removals in 19; the rest are skipped, not guessed (list in the combined PR).
  • Docs: docs/which-kind.md, docs/writing-a-plugin.md, AGENTS.md layout line.
  • Release: new exported API (File.Notes, File.Cite, NotesSections) → minor bump when released.

Part of #185.

Calls I made (please check)

  • Release notes are read as of when the pair is extracted (they can be edited later); the release page is the citation.
  • The tag listing is capped by core/versions.MaxPages (1,000 tags), enough for the 3-year window.

Related PRs

Combined into main: #232 (stack #227 → #228 → #229 → #230 → #231).

🤖 Generated with Claude Code

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]>
@adssib adssib mentioned this pull request Nov 21, 2026
9 tasks done
@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 2m 34s —— View job


⚠️ Merge after fixes. The reader work is solid and every check passes, but two new classifier paths can emit wrong events, and this repo puts precision first.

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) ✅ n/a No source added or changed. No hand-kept plugin list came back.
Provider page ✅ n/a No source added or changed.
Golden test + quote ✅ Existing goldens (textual, urllib3, mongodb-atlas) are unchanged, and go test passes over them.
testdata/README.md ✅ New row for versions/stripe-go-tags.json and versions/octokit-rest-releases.json, marked as written for the test, shape only.
Drop test ✅ New unit case: **api:** add support for new API version … under ⚠ BREAKING CHANGES gives no event.
Fetch only via env ✅ ReadAt and the listers go through env.Get and core/versions. No net/http (only net/url).
Event carries source URL + quote ✅ SourceURL: f.Cite() (tag file, or the release page for Notes); the excerpt is heading + section + bullet.
Nothing private (Rule 2) ✅ Leak guard is clean. I read the diff and PR body and found nothing private.
Contract fixtures ✅ Not touched.

Bugs (blocking, details inline)

  1. A verb label read past becomes a removal (classify.go:63). The new noise prefixes Word: , Area - and [area] also strip labels like Deprecated:, Added: and Fixed:.

    • Under a pure breaking section (Breaking changes, ⚠ BREAKING CHANGES, and now Major Changes), "Deprecated: foo" becomes just "foo".
    • bare then emits breaking removed_symbol foo.
    • Before this PR, that bullet was dropped.
  2. in/on owners in removedActive (classify.go:92). These bullets now become wrong symbols:

    • "Removed foo in setup.py" → setup.py.foo
    • "Removes bar on ios" → ios.bar
    • "… in v3" → v3.foo

    The PR's own cases only need from.

For each, a unit case that must give drop would lock the fix in.

Verified

Command Result
go build ./... ok
go vet ./... ok
gofmt -l . printed nothing
go test -race ./... all packages pass, including plugins/changelog
python3 scripts/leak_guard.py --all no banned terms (8 hashed terms checked)

make check as a whole needed an approval I don't have here, so I ran the steps above one by one. I didn't run make imports, make nethttp, make todos or make tidy separately.

I also couldn't write a scratch test file in this environment. The bug cases above come from tracing the regexes and Classify by hand, not from a run.

Non-blocking

  • parse.go:132: ending a release at # doesn't skip code fences, so a # comment in a shell example cuts the release short. This only loses bullets; it never adds a wrong event.
  • bare (classify.go:138) fires under any KindBreaking section, but its comment says "under a Removed heading". This was already true before the PR. With Major Changes added (a "highlights" heading in some non-changesets changelogs), it may be worth limiting bare to Removed-type titles.
  • ListVersions: an unknown or misspelled Ecosystem now silently falls back to listing tags, where it used to be an error. Consider allowing only the ecosystems the doc comment names (go, maven, nuget, rubygems, packagist, terraform).
  • Go modules: installed() adds /vN from major 2 on. Old majors released before Go modules (+incompatible) have no /vN. That's worth a line on the provider page of any Go source that reaches back that far.

Nice work on the Notes design: it checks that the release read is the requested tag, it treats an empty body as ErrNothingToRead rather than "no breaking changes", and it cites the release page.

"`?[0-9a-f]{7,40}`?:?\\s+",
`Thanks \[@[^\]]+\]\([^)]*\)!\s*-\s*`,
`(?:[A-Z][\w/]*(?: [A-Z][\w/]*)*) - `,
`[A-Z][a-zA-Z]+: `,

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Precision: this alternative (and the Area - and [area] ones above it) also strips a verb label. Under a pure breaking section (### Breaking changes, ⚠ BREAKING CHANGES, and now Major Changes), a bullet like

  • Deprecated: foo``
  • Added: newClient``
  • Fixed: Foo.bar``

turns into just "foo". The bare template then reads it as breaking removed_symbol foo (classify.go:138), so we'd emit a removal for something that was only deprecated, or even added. Before this PR, these bullets matched no template and were dropped.

One fix: leave a label out of the noise list when it's a change verb (added|fixed|changed|deprecated|renamed|…), or don't apply bare once a noise prefix was stripped. A unit case like {KindBreaking, "Deprecated: +"foo"+", "drop"} would lock it in.

var (
removedActive = regexp.MustCompile(`(?i)^(?:removed|remove|dropped|drop) (?:the )?(?:deprecated )?(?:` + noun + ` )?` + list +
`(?: ` + noun + `)?(?: from (?:the )?(?:` + noun + ` )?(§)(?: ` + noun + `)?)?(?: \(now called (§)\))?$`)
removedActive = regexp.MustCompile(`(?i)^(?:removed|removes|remove|dropped|drops|drop) (?:the )?(?:previously )?(?:deprecated )?(?:` + noun + ` )?` + list +

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Precision: (?:from|in|on|of) now treats any code span after in/on as the owner. clean only rejects owners that aren't identifiers, so these get through:

  • "Removed foo in setup.py" → setup.py.foo
  • "Removes bar on ios" → ios.bar
  • "Removed the deprecated foo in v3" → v3.foo

Each of these would become a wrong symbol in someone's PR. ("in 2.0" is safe: 2.0 isn't an identifier.) Could the owner be limited to from/of, or could in/on require a noun (in the X class)? The cases in the PR (Stripe's from, Neon's from the resource) only need from.

end := len(lines)
for j := i + 1; j < len(lines); j++ {
if strings.HasPrefix(lines[j], "## ") {
if strings.HasPrefix(lines[j], "## ") || strings.HasPrefix(lines[j], "# ") {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-blocking (recall only): releaseLines doesn't track code fences, unlike sections. A shell comment in a code example inside a release (```sh then # migrate) now ends the release early, so the bullets after the example are never read. Skipping fenced lines here too, the same way sections does, would fix it.

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]>
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