Skip to content

no pinned release in plugin code: every major's removed-members guide - #233

Open
adssib wants to merge 1 commit into
mainfrom
pl5-pins
Open

adssib wants to merge 1 commit into
mainfrom
pl5-pins

Conversation

@adssib

@adssib adssib commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Closes #179

What this changes

The last releases named in plugin code are gone. The three removed-members guides (NumPy, PostHog, New Relic) were each pinned to one release (NumPy2 at 2.0.0, PostHog8 at 8.0.0, NewRelic11 at 11.0.0 and a fixed docs commit). Each is now read at every major:

  • releases are listed from PyPI;
  • the guide is read at each major's first release (X.0.0);
  • the guide's path is a template per major (numpy_{major}_0_migration_guide.rst, migration-{prev}.x-to-{major}.0.md, python-agent-{major}0000.mdx);
  • a major with no guide at its tag has nothing to read (plugin.ErrNothingToRead, so the pair is skipped);
  • New Relic's notes live in a docs repo with no tags, so they're read at the newest commit that changed the major's note (Untagged), looked up when they're read.

Also:

  • changelog.Textual0860 / Urllib3200 and sdkguide.AnthropicV1 (the golden tests' cases) move into _test.go files.
  • The scaffold (cmd/new-plugin) no longer writes a release into a plugin's non-test code.
  • plugins/all's new TestNoPinnedReleaseInPluginCode fails on a release number (X.Y.Z) or a full commit SHA in any string literal of any plugin's non-test code. Comments may still say which release a reader was checked at.
  • core/versions: FirstOfMajor (moved from sdkguide), and PyPIReleasesWithYanked. New Relic's 11.0.0, the release its note documents, is yanked on PyPI, so a guide lists yanked releases too. The golden stays at 11.0.0, and a pin on 11.0.1 still crosses it.
  • migrationguide.Guide: GuideURL(ctx, env, v) (string, error) (it may look up a commit), and Read(page, sourceURL, from, to, now): the event's version and source_url come from the release read, not the guide's field.

Every existing golden is byte-identical.

#179's checklist

  • Every source implements ListVersions / ReadAt / Extract (since plugins#225; the members guides now list every release, not one).
  • Version order in one place (versions.Compare).
  • No pinned tag or version in plugin code; tests pin versions through saved fixtures. A test checks this (TestNoPinnedReleaseInPluginCode).
  • Events for a pair carry previous_version.
  • A test per versioned kind lists versions and extracts consecutive pairs: openapi, changelog, migrationguide (sdk and members), apisurface. catalog gets its three-pair test in this stack (github/graphql, add github/graphql: announced GraphQL removals #239).
  • Every existing golden is byte-identical.
  • Go proxy and Maven version sources: not added. No registered source reads a Go module or a Maven artifact yet. They come with the first source that needs one, not before.
  • Wayback at a date is I19.11, a separate ticket.

Checklist

  • Metadata complete in the registration: three sources' Watches and URLs no longer name a release (I read them)
  • Every commit is signed off (DCO)
  • Goldens unchanged (NumPy, PostHog, New Relic, Anthropic, urllib3, Textual)
  • testdata/README.md lists the two new test files (GitHub commit-list shapes)
  • Fetches only through env.Get
  • make check passes locally
  • Nothing private

Calls I made (please check)

  • NumPy's rename rule now applies to any future major's guide. A row that is exactly "Use np.X instead." becomes a rename. That held for 2.0, whose guide says each such replacement works on 1.x; a later guide might not. Written down as a known gap in providers/numpy.md.
  • PostHog and New Relic keep their hand-checked Paths / DropIns / StillWork for later majors. These are keyed by name. A name they don't cover gets the conservative default: removed_symbol, never a rename.
  • A 404 for a major's guide is "nothing to read" (skipped), not a failure. Most majors before a project started writing guides have none.

Related PRs

🤖 Generated with Claude Code

@claude

claude Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

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


⚠️ Merge after fixes. The removed-members guides are now read at every major, and every golden is byte-identical. One problem: a change in core/github makes five OpenAPI sources fail silently.

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) ✅ plugins/migrationguide/migrationguide.go: the Watches and URLs of NumPy, PostHog and New Relic no longer name a release. Each one names the major's guide and PyPI. No hand-kept list came back.
Provider page ✅ providers/{numpy,posthog,newrelic}.md now describe reading every major, with the 2.0, 8.0.0 and 11.0.0 guides as the checked examples. New known gaps are listed (NumPy's rename rule; Paths/DropIns checked only against the current major).
Golden test and quote ✅ No file under testdata/golden/ changed. testdata/README.md has rows for the two new commit-list fixtures, each marked as shape only.
Drop test ✅ The existing drop tests still pass. New: TestAMajorWithNoGuideHasNothingToRead (404 at the tag, and no commit for the note).
Fetch only via env ✅ The new commit lookup goes through env.Get (members.go GuideURL). No net/http was added.
No pinned release ✅ TestNoPinnedReleaseInPluginCode passes. The pins moved into _test.go files.
Nothing private (Rule 2) ✅ Leak guard is clean, and I found nothing private in the code, the docs or the PR text.

Bugs

  1. core/github/github.go:81: LatestCommit now wraps ErrNothingToRead for every caller. The OpenAPI adapters for Appwrite, Convex, Neon, PlanetScale and Supabase call it too, and they all wrap the error with %w. If one of those providers moves its spec, the runner will now skip the pair quietly; today it fails, so someone notices. This doesn't create wrong events, but it hides a broken source. Fix: return a neutral github.ErrNoCommit from LatestCommit, and map it to ErrNothingToRead only in members.Guide.GuideURL. I left a suggestion inline.

I found nothing else blocking. I checked these:

  • FirstOfMajor gates every guide fetch, so a minor or patch release never fetches anything.
  • A missing section or table in a later major's note returns ErrNothingToRead (members.go:206/216/250, markdown.go:60/73/117), so the pair is skipped, not failed.
  • Precision on later majors is conservative where it has to be. PostHog keeps NewReplacements: true. New Relic's non-nil DropIns means only listed names become renames. The NumPy rename rule is the one open call, and you've already flagged it in providers/numpy.md.

Verified

  • go build ./...: OK
  • go vet ./...: OK
  • gofmt -l .: printed nothing
  • go test -race ./...: every package passes, including plugins/all (TestNoPinnedReleaseInPluginCode), migrationguide, members and sdkguide
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • Not run: make imports nethttp todos tidy. It needs approval in this runner. The diff adds no net/http and no TODO(new-plugin) outside the scaffold templates.

Non-blocking

  • New Relic's source URL can change over time. Untagged reads the newest commit that changed the note, so if New Relic later edits the 11.0.0 note, a re-read cites a different SHA. That's fine as long as the hosted service extracts each version once. Consider adding one line to providers/newrelic.md saying the cited commit is the newest one when the note was read.
  • Yanked releases now appear for all three guides, not just New Relic, because all three share Guide.Releases. NumPy and PostHog have no yanked X.0.0 today, so nothing changes for them. If yanked releases should stay specific to New Relic, a per-guide flag would do it.
  • TestNoPinnedReleaseInPluginCode only checks plugins/. That's the right scope for this PR. A short comment saying core/ and cmd/ are excluded on purpose would help the next reader.

Thanks for the clear "Calls I made" section. It made the precision tradeoffs easy to check.

Comment thread core/github/github.go
}
if len(commits) == 0 || commits[0].SHA == "" {
return "", fmt.Errorf("github lists no commit")
return "", fmt.Errorf("github lists no commit: %w", plugin.ErrNothingToRead)

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This changes behaviour for five other sources, not just New Relic. LatestCommit is also called by the OpenAPI adapters for Appwrite, Convex, Neon, PlanetScale and Supabase (plugins/openapi/adapter/{appwrite,convex,neon,planetscale,supabase}.go), and each one wraps the error with %w. So if one of those providers moves or renames its spec, the empty commit list now reaches the runner as ErrNothingToRead. The pair gets skipped quietly, where today it fails and someone notices the broken source.

Suggestion: keep a neutral sentinel here, e.g. var ErrNoCommit = errors.New("github lists no commit"), and turn it into "nothing to read" only in members.Guide.GuideURL, where an empty list really does mean "this major has no note":

sha, err := github.LatestCommit(ctx, env.Get, g.commitsURL(major))
if errors.Is(err, github.ErrNoCommit) {
	return "", fmt.Errorf("no %s note for %s: %w", g.Package, v.ID, plugin.ErrNothingToRead)
}

As a side effect, core/github would no longer need to import core/plugin.

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.

I19.8 · ListVersions, ReadAt and Extract for every kind; no pinned versions

1 participant