diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index 7b08632..ba98dc1 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -159,16 +159,15 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { defDir: "plugins/migrationguide/sdkguide", def: `package sdkguide -// {{.Ident}} is {{.Provider}}'s SDK guide to a major release (MIGRATION.md at -// the release tag). +// {{.Ident}} is {{.Provider}}'s SDK guide to each major release (MIGRATION.md +// at the major's first tag), its releases listed from PyPI. // -// ` + todo + `: the PyPI name, the repo, the major release and the calls the -// guide's table names. Say what you checked, with the date. +// ` + todo + `: the PyPI name, the repo and the calls the guide's table +// names. Say what you checked, with the date. var {{.Ident}} = Guide{ API: "{{.ID}}", Package: "{{.PyPI}}", Repo: "TODO-owner/TODO-repo", - Major: 1, Methods: "` + "`TODO.create()`" + `", Symbols: []string{"TODO.create"}, } @@ -216,9 +215,10 @@ const {{.Lower}}Previous = "0.0.0" // {{.Lower}}Ingest is the version pair {{.Lower}}Previous -> the guide's // major over a saved copy of the guide. +// ` + todo + `: the major the saved guide is for. func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() - g := sdkguide.{{.Ident}} + g := sdkguide.{{.Ident}}.At(1) env := kittest.Env(t, kittest.Pages{g.URL(): file}) return kittest.Versions(t, env, Plugin{Guide: g}, plugin.Version{ID: {{.Lower}}Previous, Ref: "v" + {{.Lower}}Previous}, plugin.Version{ID: g.Version(), Ref: "v" + g.Version()}) @@ -233,19 +233,19 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { defDir: "plugins/migrationguide/members", def: `package members -// {{.Ident}} is {{.Provider}}'s migration guide to a release, with its table -// of removed members. +// {{.Ident}} is {{.Provider}}'s migration guide to each major, with its table +// of removed members, read at the major's first tag. // -// ` + todo + `: the package, how the guide writes the module, the release, -// the repo, the guide's path at the release tag and the heading the table is -// under. Say what you checked, with the date. +// ` + todo + `: the package, how the guide writes the module, the repo, the +// guide's path at a major's tag ({major} for its number, {prev} for the one +// before) and the heading the table is under. Say what you checked, with the +// date. var {{.Ident}} = Guide{ API: "{{.ID}}", Package: "{{.PyPI}}", Module: "{{.Module}}", - Release: "1.0.0", Repo: "TODO-owner/TODO-repo", - Path: "TODO/migration_guide.rst", + Path: "TODO/migration_guide_{major}.rst", Section: "Removed members", } `, @@ -300,13 +300,17 @@ func Test{{.Ident}}DropsANonChange(t *testing.T) { // ` + todo + `: the real release before it. const {{.Lower}}Previous = "0.0.0" -// {{.Lower}}Ingest is the version pair {{.Lower}}Previous -> the guide's -// release over a saved copy of the guide. +// {{.Lower}}Release is the major's first release the saved guide is for. +// ` + todo + `: the real release. +const {{.Lower}}Release = "1.0.0" + +// {{.Lower}}Ingest is the version pair {{.Lower}}Previous -> +// {{.Lower}}Release over a saved copy of the guide. func {{.Lower}}Ingest(t *testing.T, file string) []event.Event { t.Helper() g := members.{{.Ident}} - env := kittest.Env(t, kittest.Pages{g.URL(): file}) - return kittest.Versions(t, env, Plugin{Guide: g}, plugin.Version{ID: {{.Lower}}Previous}, plugin.Version{ID: g.Release}) + env := kittest.Env(t, kittest.Pages{g.RawURL("v"+{{.Lower}}Release, 1): file}) + return kittest.Versions(t, env, Plugin{Guide: g}, plugin.Version{ID: {{.Lower}}Previous}, plugin.Version{ID: {{.Lower}}Release}) } `, imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/core/plugin", "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members"}, @@ -328,9 +332,6 @@ var {{.Ident}} = File{ API: "{{.ID}}", Package: "{{.PyPI}}", Ecosystem: "pypi", Module: "{{.Module}}", Repo: "TODO-owner/TODO-repo", TagPrefix: "v", Path: "CHANGELOG.md", } - -// {{.Ident}}Golden is the release the golden test pins. -var {{.Ident}}Golden = {{.Ident}}.At("1.0.0") `, register: `plugin.Register(Plugin{File: {{.Ident}}})`, pluginOf: `Plugin{File: {{.Ident}}}`, @@ -345,7 +346,12 @@ var {{.Ident}}Golden = {{.Ident}}.At("1.0.0") - A placeholder entry. `}, source: "{{.File}}-CHANGELOG.md", - ingest: `// {{.Lower}}Previous is the release before {{.Ident}}Golden's on the + ingest: `// {{.Ident}}Golden is the release the golden test pins: only a test names +// one. +// ` + todo + `: the real release. +var {{.Ident}}Golden = {{.Ident}}.At("1.0.0") + +// {{.Lower}}Previous is the release before {{.Ident}}Golden's on the // registry: the pair's older side. // ` + todo + `: the real release before it. const {{.Lower}}Previous = "0.0.0" diff --git a/core/github/github.go b/core/github/github.go index b056470..f0db860 100644 --- a/core/github/github.go +++ b/core/github/github.go @@ -16,6 +16,7 @@ import ( "time" "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // API is GitHub's REST API. @@ -63,7 +64,8 @@ func LatestRelease(ctx context.Context, get Getter, url string) (string, error) } // LatestCommit reads a commit list (url: commits?path=&per_page=1, newest -// first) and returns the newest commit's SHA, or an error when it lists none. +// first) and returns the newest commit's SHA, or an error when it lists none +// (plugin.ErrNothingToRead: no commit ever changed the path). func LatestCommit(ctx context.Context, get Getter, url string) (string, error) { body, err := get(ctx, url) if err != nil { @@ -76,7 +78,7 @@ func LatestCommit(ctx context.Context, get Getter, url string) (string, error) { return "", fmt.Errorf("parsing github commits response: %w", err) } if len(commits) == 0 || commits[0].SHA == "" { - return "", fmt.Errorf("github lists no commit") + return "", fmt.Errorf("github lists no commit: %w", plugin.ErrNothingToRead) } return commits[0].SHA, nil } diff --git a/core/versions/versions.go b/core/versions/versions.go index 6684245..5cf8d3d 100644 --- a/core/versions/versions.go +++ b/core/versions/versions.go @@ -149,6 +149,16 @@ func GitHubCommits(ctx context.Context, get Getter, repo, path string) ([]plugin // yanked releases, none without files), oldest first by version. The Ref is // the version; a plugin that reads a repo at a tag maps it. func PyPIReleases(ctx context.Context, get Getter, pkg string) ([]plugin.Version, error) { + return pypiReleases(ctx, get, pkg, false) +} + +// PyPIReleasesWithYanked are PyPIReleases and the yanked final releases too: +// for a source whose change can be documented at a release later yanked. +func PyPIReleasesWithYanked(ctx context.Context, get Getter, pkg string) ([]plugin.Version, error) { + return pypiReleases(ctx, get, pkg, true) +} + +func pypiReleases(ctx context.Context, get Getter, pkg string, withYanked bool) ([]plugin.Version, error) { body, err := get(ctx, PyPI+"/pypi/"+url.PathEscape(pkg)+"/json") if err != nil { return nil, fmt.Errorf("listing %s's releases on PyPI: %w", pkg, err) @@ -175,7 +185,7 @@ func PyPIReleases(ctx context.Context, get Getter, pkg string) ([]plugin.Version first = f.Uploaded } } - if yanked { + if yanked && !withYanked { continue } out = append(out, plugin.Version{ID: v, Released: first.UTC(), Ref: v, URL: "https://pypi.org/project/" + pkg + "/" + v + "/"}) @@ -249,6 +259,12 @@ func Major(v string) int { return n } +// FirstOfMajor is true for X.0.0, the first release of a major (X > 0). +func FirstOfMajor(v string) bool { + m := Major(v) + return m > 0 && v == fmt.Sprintf("%d.0.0", m) +} + // Pairs are the consecutive pairs of vs, oldest first: what a backfill // extracts, one pair at a time. func Pairs(vs []plugin.Version) [][2]plugin.Version { diff --git a/core/versions/versions_test.go b/core/versions/versions_test.go index e6d3e40..eef3ce1 100644 --- a/core/versions/versions_test.go +++ b/core/versions/versions_test.go @@ -116,6 +116,21 @@ func TestPyPIReleasesAreFinalAndNotYanked(t *testing.T) { if !vs[0].Released.Equal(time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)) { t.Errorf("released %v", vs[0].Released) } + all, err := PyPIReleasesWithYanked(context.Background(), get, "acme") + if err != nil { + t.Fatal(err) + } + if got := ids(all); got != "1.0.0@1.0.0 1.9.0@1.9.0 1.9.1@1.9.1 1.10.0@1.10.0" { + t.Errorf("with yanked: got %s", got) + } +} + +func TestFirstOfMajor(t *testing.T) { + for v, want := range map[string]bool{"2.0.0": true, "11.0.0": true, "2.0.1": false, "2.1.0": false, "0.0.0": false, "2.0": false, "2.0.0rc1": false} { + if got := FirstOfMajor(v); got != want { + t.Errorf("FirstOfMajor(%q) = %v, want %v", v, got, want) + } + } } func TestNPMReleases(t *testing.T) { diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 01b4ea7..1c41f91 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -136,7 +136,7 @@ When a release or a page has no part the reader can use (a changelog with no sec A source that has versions (a spec's releases, a package's releases, a guide per major, the commits that changed a file) is read version by version, so a customer several versions behind gets every step: the runner lists the versions, reads each consecutive pair with `ReadAt` and extracts it once (a released version never changes). -- **List** with [`core/versions`](../core/versions/versions.go): `GitHubReleases`, `GitHubTags`, `GitHubCommits` (the commits that changed a file), `PyPIReleases`, `NPMReleases`, `GitHubPages` (any other GitHub list, page by page). An OpenAPI adapter lists its own versions (`adapter.Lister`): every adapter does. Never pin a tag in code: a version you need for a golden test is a pinned *case* in the test (`changelog.Urllib3.At("2.0.0")`), not the registered source. +- **List** with [`core/versions`](../core/versions/versions.go): `GitHubReleases`, `GitHubTags`, `GitHubCommits` (the commits that changed a file), `PyPIReleases` (`PyPIReleasesWithYanked` when a change can be documented at a release later yanked), `NPMReleases`, `GitHubPages` (any other GitHub list, page by page). An OpenAPI adapter lists its own versions (`adapter.Lister`): every adapter does. Never pin a tag in code: a version you need for a golden test is a pinned *case* in the test (`changelog.Urllib3.At("2.0.0")`, in a `_test.go` file), not the registered source; `plugins/all`'s `TestNoPinnedReleaseInPluginCode` fails on a release number or commit SHA in any plugin's non-test code. - **Read at** a version's `Ref` (a tag, a commit SHA) and return the exact URL read as the snapshot's `SourceURL`: it's the events' citation. - **Extract** sets `previous_version` to `from`'s version: every `api_operation` and `package_release` event must name it (the contract's rule 13). `from` is zero only for the first version read, which has nothing to compare: patch-it's hosted ingestion service reads that version as its first snapshot and extracts nothing from it, so a version pair always starts at a real `from` (an `api_operation` or `package_release` event extracted from zero would be rejected). diff --git a/plugins/all/pins_test.go b/plugins/all/pins_test.go new file mode 100644 index 0000000..62fd2a1 --- /dev/null +++ b/plugins/all/pins_test.go @@ -0,0 +1,56 @@ +package all + +import ( + "go/ast" + "go/parser" + "go/token" + "io/fs" + "path/filepath" + "regexp" + "strconv" + "strings" + "testing" +) + +// release is a specific release in a string: a version number with three +// parts ("2.0.0", "v0.86.0", "posthog-v8.0.0", "python-agent-110000" aside) +// or a full commit SHA. A source lists its versions (PyPI, npm, tags, +// commits); only a test pins one, through its saved fixtures. +var release = regexp.MustCompile(`(^|[^0-9A-Za-z.])v?\d+\.\d+\.\d+([^0-9]|$)|(^|[^0-9a-f])[0-9a-f]{40}([^0-9a-f]|$)`) + +// No plugin's code names a specific release or commit: every version comes +// from where the source publishes them. Comments may name the release a +// reader was checked at; a string the code uses may not. +func TestNoPinnedReleaseInPluginCode(t *testing.T) { + fset := token.NewFileSet() + err := filepath.WalkDir("..", func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() && d.Name() == "testdata" { + return filepath.SkipDir + } + if d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") { + return nil + } + f, err := parser.ParseFile(fset, path, nil, 0) + if err != nil { + return err + } + ast.Inspect(f, func(n ast.Node) bool { + lit, ok := n.(*ast.BasicLit) + if !ok || lit.Kind != token.STRING { + return true + } + s, err := strconv.Unquote(lit.Value) + if err == nil && release.MatchString(s) { + t.Errorf("%s: %q names a specific release; list versions from the source and pin one only in a test", fset.Position(lit.Pos()), s) + } + return true + }) + return nil + }) + if err != nil { + t.Fatal(err) + } +} diff --git a/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index 90a8a63..f267ce5 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -98,12 +98,6 @@ var Urllib3 = File{ Repo: "urllib3/urllib3", Path: "CHANGES.rst", } -// The releases the golden files pin. -var ( - Textual0860 = Textual.At("0.86.0") - Urllib3200 = Urllib3.At("2.0.0") -) - // URL is the changelog as it was at the (pinned) tag: its own provenance. func (f File) URL() string { return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", f.Repo, f.Tag, f.Path) diff --git a/plugins/changelog/pinned_test.go b/plugins/changelog/pinned_test.go new file mode 100644 index 0000000..f048a7b --- /dev/null +++ b/plugins/changelog/pinned_test.go @@ -0,0 +1,8 @@ +package changelog + +// The releases the golden files pin. Only a test names a release: the +// registered sources list theirs from PyPI. +var ( + Textual0860 = Textual.At("0.86.0") + Urllib3200 = Urllib3.At("2.0.0") +) diff --git a/plugins/migrationguide/golden_test.go b/plugins/migrationguide/golden_test.go index 7612269..164eed6 100644 --- a/plugins/migrationguide/golden_test.go +++ b/plugins/migrationguide/golden_test.go @@ -12,7 +12,7 @@ import ( // The guide at tag v1.0.0 (saved 2026-10-17) in, every event out: the pair // from 0.75.0, the release before on PyPI. func TestGolden(t *testing.T) { - kittest.Golden(t, "testdata/golden/anthropic-1.0.0.json", anthropicV1(t, sdkguide.AnthropicV1)) + kittest.Golden(t, "testdata/golden/anthropic-1.0.0.json", anthropicV1(t, anthropicGuideV1)) } // anthropicV1 is g's pair 0.75.0 -> 1.0.0 over the saved v1.0.0 guide, as @@ -20,7 +20,7 @@ func TestGolden(t *testing.T) { // it has no guide, and nothing is fetched for it. func anthropicV1(t *testing.T, g sdkguide.Guide, more ...kittest.Pages) []event.Event { t.Helper() - pages := kittest.Pages{sdkguide.AnthropicV1.URL(): "sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md"} + pages := kittest.Pages{anthropicGuideV1.URL(): "sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md"} for _, m := range more { for k, v := range m { pages[k] = v @@ -29,3 +29,7 @@ func anthropicV1(t *testing.T, g sdkguide.Guide, more ...kittest.Pages) []event. return kittest.Versions(t, kittest.Env(t, pages), Plugin{Guide: g}, plugin.Version{ID: "0.75.0", Ref: "v0.75.0"}, plugin.Version{ID: "1.0.0", Ref: "v1.0.0"}) } + +// anthropicGuideV1 is anthropic-sdk-python's guide pinned to 1.0.0: what the +// golden pins. Only a test names a release. +var anthropicGuideV1 = sdkguide.Anthropic.At(1) diff --git a/plugins/migrationguide/members/export_test.go b/plugins/migrationguide/members/export_test.go index 8667a92..b5dbb04 100644 --- a/plugins/migrationguide/members/export_test.go +++ b/plugins/migrationguide/members/export_test.go @@ -7,5 +7,6 @@ var ( SoleName = soleName ) -func (g Guide) Tag() string { return g.tag() } +func (g Guide) TagOf(release string) string { return g.tagOf(release) } +func (g Guide) CommitsURL(major int) string { return g.commitsURL(major) } func (g Guide) AbsoluteLinks(s string) string { return g.absoluteLinks(s) } diff --git a/plugins/migrationguide/members/golden_test.go b/plugins/migrationguide/members/golden_test.go index b76686b..e28bb60 100644 --- a/plugins/migrationguide/members/golden_test.go +++ b/plugins/migrationguide/members/golden_test.go @@ -6,6 +6,7 @@ import ( "github.com/patch-it-dev/patch-it-plugins/core/event" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/versions" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" . "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" // the reader under test @@ -14,16 +15,35 @@ import ( // The guide at tag v2.0.0 (saved 2026-11-04) in, every event out: the pair // from 1.26.4, the release before on PyPI. func TestGolden(t *testing.T) { - got := release(t, NumPy2, "testdata/numpy_2_0_migration_guide-v2.0.0.rst", "1.26.4") + got := release(t, NumPy, "testdata/numpy_2_0_migration_guide-v2.0.0.rst", "1.26.4", "2.0.0") kittest.Golden(t, "../testdata/golden/numpy-2.0.0.json", got) } -// release is the pair previous -> the release g documents, over the guide -// saved as file, as patch-it's hosted ingestion service extracts it. -// previous isn't the guide's release: it has no guide, and nothing is -// fetched for it. -func release(t *testing.T, g Guide, file, previous string) []event.Event { +// release is the pair previous -> rel, the first release of a major, over +// the guide saved as file, as patch-it's hosted ingestion service extracts +// it. previous isn't a major's first release: it has no guide, and nothing +// is fetched for it. +func release(t *testing.T, g Guide, file, previous, rel string) []event.Event { t.Helper() - env := kittest.Env(t, kittest.Pages{g.URL(): file}) - return kittest.Versions(t, env, migrationguide.Plugin{Guide: g}, plugin.Version{ID: previous}, plugin.Version{ID: g.Release}) + return kittest.Versions(t, guideEnv(t, g, file, rel), migrationguide.Plugin{Guide: g}, plugin.Version{ID: previous}, plugin.Version{ID: rel}) +} + +// newrelicCommit is the docs-website commit New Relic's saved release note +// was fetched at, and newrelicCommits GitHub's answer naming it as the +// newest commit that changed the note. +const ( + newrelicCommit = "f0b4f817bf9a7b76a78e26609369a8a7ce764c8e" + newrelicCommits = "testdata/github-commits-python-agent-110000.json" +) + +// guideEnv serves file as g's guide for rel: at rel's tag, or (Untagged) at +// the commit GitHub names for it. +func guideEnv(t *testing.T, g Guide, file, rel string) plugin.Env { + t.Helper() + major := versions.Major(rel) + pages := kittest.Pages{g.RawURL(g.TagOf(rel), major): file} + if g.Untagged { + pages = kittest.Pages{g.CommitsURL(major): newrelicCommits, g.RawURL(newrelicCommit, major): file} + } + return kittest.Env(t, pages) } diff --git a/plugins/migrationguide/members/members.go b/plugins/migrationguide/members/members.go index 033b05f..7e029af 100644 --- a/plugins/migrationguide/members/members.go +++ b/plugins/migrationguide/members/members.go @@ -2,9 +2,12 @@ // that removed members of its top-level module, read from the release's own // migration guide at its tag: change event v2's `package_release` subject. // The kind (plugins/migrationguide) reads the guide and calls Read; this -// package knows where the guide is and how its table reads. NumPy 2.0 first: its guide lists about 60 members of the main `np` -// namespace that were removed, each with a migration guideline, and code using -// one raises AttributeError on NumPy 2 (checked 2026-11-04 at tag v2.0.0). +// package knows where the guide is and how its table reads. A guide is read +// at the first release of each major (X.0.0), listed from PyPI: nothing in +// the code names a release. NumPy first: its 2.0 guide lists about 60 +// members of the main `np` namespace that were removed, each with a +// migration guideline, and code using one raises AttributeError on NumPy 2 +// (checked 2026-11-04 at tag v2.0.0). // // A row whose guideline is exactly one replacement in the module ("Use // “np.float64“ instead.") becomes a `renamed_symbol` with that replacement: @@ -24,33 +27,40 @@ import ( "context" "fmt" "log" + "net/url" "regexp" "slices" + "strconv" "strings" "time" "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/plugin" "github.com/patch-it-dev/patch-it-plugins/core/versions" ) -// Guide is one package's guide to one release. +// Guide is one package's guide to each of its majors. type Guide struct { API string // the source id the events carry: "numpy/numpy" Package string // the PyPI name: "numpy" Module string // how the guide writes the module in a replacement: "np" - Release string // "2.0.0" Repo string // owner/name on GitHub - Path string // the guide's path in the repo at the release tag + // Path is the guide's path in the repo for a major, "{major}" standing + // for the major's number and "{prev}" for the one before: + // "doc/source/numpy_{major}_0_migration_guide.rst" is + // doc/source/numpy_2_0_migration_guide.rst for 2.0.0. + Path string Section string // the heading the table is under // TagPrefix makes a release's git tag: TagPrefix + version ("" is "v": - // v2.0.0; PostHog's is "posthog-v"). The guide is read at Release's tag. + // v2.0.0; PostHog's is "posthog-v"). A major's guide is read at the tag + // of its first release. TagPrefix string - // DocsRef, when the guide isn't in the package's own repo but in a docs - // repo with no release tags (New Relic's release notes), is the commit - // of Repo the guide is read at. - DocsRef string + // Untagged is a guide that isn't in the package's own repo but in a docs + // repo with no release tags (New Relic's release notes): it is read at + // the newest commit that changed its path, looked up when it's read. + Untagged bool // Format is how the table is written: FormatRST (the default) or // FormatMarkdown. Format Format @@ -111,13 +121,8 @@ const ( FormatMarkdown Format = "markdown" ) -func (g Guide) tag() string { return g.tagOf(g.Release) } - -// tagOf is the git ref a release of the package is read at. +// tagOf is the git tag of a release of the package. func (g Guide) tagOf(release string) string { - if g.DocsRef != "" { - return g.DocsRef - } if g.TagPrefix != "" { return g.TagPrefix + release } @@ -138,21 +143,33 @@ func (g Guide) header() string { return "removed member" } -// NumPy2 is NumPy's 2.0 migration guide, "Main namespace" table. -var NumPy2 = Guide{ +// NumPy is NumPy's migration guide to a major, "Main namespace" table +// (doc/source/numpy_2_0_migration_guide.rst at v2.0.0, checked 2026-11-04; +// no other major has one yet, checked 2026-11-20). +var NumPy = Guide{ API: "numpy/numpy", Package: "numpy", Module: "np", - Release: "2.0.0", Repo: "numpy/numpy", - Path: "doc/source/numpy_2_0_migration_guide.rst", + Path: "doc/source/numpy_{major}_0_migration_guide.rst", Section: "Main namespace", Effect: "code using it raises AttributeError", } -// URL is the guide as it was at the release tag: its own provenance. -func (g Guide) URL() string { - return fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s", g.Repo, g.tag(), g.Path) +// PathAt is the guide's path for a major. +func (g Guide) PathAt(major int) string { + return strings.NewReplacer("{major}", strconv.Itoa(major), "{prev}", strconv.Itoa(major-1)).Replace(g.Path) +} + +// commitsURL lists the newest commit that changed a major's guide. +func (g Guide) commitsURL(major int) string { + return fmt.Sprintf("%s/repos/%s/commits?path=%s&per_page=1", github.API, g.Repo, url.QueryEscape(g.PathAt(major))) +} + +// RawURL is the guide for a major at a git ref (a tag or a commit): its own +// provenance, as it never changes. +func (g Guide) RawURL(ref string, major int) string { + return fmt.Sprintf("%s/%s/%s/%s", github.Raw, g.Repo, ref, g.PathAt(major)) } // Removal is one removed member and the guide's guideline for it. @@ -245,10 +262,13 @@ func parseRST(page []byte, g Guide) ([]Removal, error) { // Slug is the source id the events carry: "numpy/numpy". func (g Guide) Slug() string { return g.API } -// Releases is every final release of the package on PyPI, oldest first, -// each with the ref its guide would be read at. +// Releases is every final release of the package on PyPI, yanked ones +// included, oldest first, each with its tag. A yanked release stays: it can +// be the one a guide documents (New Relic's 11.0.0, yanked for a +// server-side configuration issue), and a pin on a later one still crosses +// it. func (g Guide) Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, error) { - vs, err := versions.PyPIReleases(ctx, env.Get, g.Package) + vs, err := versions.PyPIReleasesWithYanked(ctx, env.Get, g.Package) if err != nil { return nil, err } @@ -258,34 +278,44 @@ func (g Guide) Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, return vs, nil } -// GuideURL is the guide when v is the release it documents; any other -// release has no guide (""). -func (g Guide) GuideURL(v plugin.Version) string { - if v.ID != g.Release { - return "" +// GuideURL is the guide for v's major when v is its first release (X.0.0), +// at v's tag or, Untagged, at the newest commit that changed the guide's +// path; any other release has no guide (""). A major whose guide's path has +// no commit has nothing to read (plugin.ErrNothingToRead). +func (g Guide) GuideURL(ctx context.Context, env plugin.Env, v plugin.Version) (string, error) { + if !versions.FirstOfMajor(v.ID) { + return "", nil + } + major := versions.Major(v.ID) + if !g.Untagged { + return g.RawURL(g.tagOf(v.ID), major), nil + } + sha, err := github.LatestCommit(ctx, env.Get, g.commitsURL(major)) + if err != nil { + return "", fmt.Errorf("the commit %s's guide for %s is read at: %w", g.Package, v.ID, err) } - return g.URL() + return g.RawURL(sha, major), nil } -// Read is an event per removed member in the guide, with previous_version -// from's release. -func (g Guide) Read(page []byte, from, _ plugin.Version, now time.Time) (events []event.Event, rejected []error, err error) { +// Read is an event per removed member in the guide to's release documents, +// read from sourceURL, with previous_version from's release. +func (g Guide) Read(page []byte, sourceURL string, from, to plugin.Version, now time.Time) (events []event.Event, rejected []error, err error) { removals, err := Parse(page, g) if err != nil { return nil, nil, err } for _, r := range removals { if r.Dropped != "" { - log.Printf("%s %s: dropped %q: %s", g.Package, g.Release, r.Member, r.Dropped) + log.Printf("%s %s: dropped %q: %s", g.Package, to.ID, r.Member, r.Dropped) continue } subject := event.Subject{ Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.Package, Change: event.PackageRemovedSymbol, Symbols: []string{r.Member}, } - desc := fmt.Sprintf("`%s` was removed in %s %s.", r.Member, g.Package, g.Release) + desc := fmt.Sprintf("`%s` was removed in %s %s.", r.Member, g.Package, to.ID) if g.Effect != "" { - desc = fmt.Sprintf("%s.%s was removed in %s %s: %s.", g.Module, r.Member, g.Package, g.Release, g.Effect) + desc = fmt.Sprintf("%s.%s was removed in %s %s: %s.", g.Module, r.Member, g.Package, to.ID, g.Effect) } if r.Replacement != "" && !g.NewReplacements && (g.DropIns == nil || slices.Contains(g.DropIns, r.Member)) { subject.Change, subject.Replacement = event.PackageRenamedSymbol, r.Replacement @@ -293,13 +323,13 @@ func (g Guide) Read(page []byte, from, _ plugin.Version, now time.Time) (events e := event.Event{ API: g.API, PreviousVersion: from.ID, - Version: g.Release, + Version: to.ID, ChangeType: event.ChangeTypeBreaking, Breaking: true, Subject: subject, Description: desc, - MigrationHint: fmt.Sprintf("%s (%s's %s for %s)", g.absoluteLinks(r.Guideline), g.Package, g.doc(), g.Release), - SourceURL: g.URL(), + MigrationHint: fmt.Sprintf("%s (%s's %s for %s)", g.absoluteLinks(r.Guideline), g.Package, g.doc(), to.ID), + SourceURL: sourceURL, SourceExcerpt: r.Excerpt, Confidence: 1.0, DetectedAt: now, diff --git a/plugins/migrationguide/members/members_test.go b/plugins/migrationguide/members/members_test.go index 7237856..c568650 100644 --- a/plugins/migrationguide/members/members_test.go +++ b/plugins/migrationguide/members/members_test.go @@ -18,7 +18,7 @@ func guide(t *testing.T) []byte { func byMember(t *testing.T) map[string]Removal { t.Helper() - rs, err := Parse(guide(t), NumPy2) + rs, err := Parse(guide(t), NumPy) if err != nil { t.Fatal(err) } @@ -71,10 +71,7 @@ func TestOnlyOnePlainReplacementInNpIsARename(t *testing.T) { func TestTheGuideStoresOneEventPerMemberAndARerunNothing(t *testing.T) { // The guide at the v2.0.0 tag, and nothing else; kittest extracts the // pair again and fails on anything new. - if NumPy2.URL() != "https://raw.githubusercontent.com/numpy/numpy/v2.0.0/doc/source/numpy_2_0_migration_guide.rst" { - t.Fatalf("the guide is read at %s, not the v2.0.0 tag", NumPy2.URL()) - } - events := release(t, NumPy2, "testdata/numpy_2_0_migration_guide-v2.0.0.rst", "1.26.4") + events := release(t, NumPy, "testdata/numpy_2_0_migration_guide-v2.0.0.rst", "1.26.4", "2.0.0") if len(events) != 56 { t.Fatalf("%d events, want 56", len(events)) } diff --git a/plugins/migrationguide/members/newrelic.go b/plugins/migrationguide/members/newrelic.go index a4bc4fb..13bfff3 100644 --- a/plugins/migrationguide/members/newrelic.go +++ b/plugins/migrationguide/members/newrelic.go @@ -1,16 +1,19 @@ package members -// NewRelic11 is New Relic's release note for the Python agent 11.0.0 (the -// `newrelic` package on PyPI), in newrelic/docs-website at commit -// f0b4f817bf9a7b76a78e26609369a8a7ce764c8e: that repo has no tags, so the -// commit stands in for one. Its "Removed features" section's first table, -// | Legacy API | Replacement API |: "The following APIs have been removed". -// Checked 2026-11-19. +// NewRelic is New Relic's release note for each major of the Python agent +// (the `newrelic` package on PyPI), in newrelic/docs-website as +// python-agent-0000.mdx (python-agent-110000.mdx for 11.0.0; 9.0.0 +// to 13.0.0 are there, checked 2026-11-20). That repo has no tags, so the +// newest commit that changed the note stands in for one (Untagged). Its +// "Removed features" section's first table, | Legacy API | Replacement API |: +// "The following APIs have been removed". A note without that section has +// nothing to read. 11.0.0's, at commit f0b4f817 (checked 2026-11-19), is +// the one described below. // // 11.0.0 is yanked on PyPI ("Issues with server-side configuration"); // 11.0.1 has the same public API (newrelic/agent.py and newrelic/api/log.py // are byte-identical at v11.0.0 and v11.0.1). The version stays 11.0.0, the -// release that made the change. +// release that made the change: Releases keeps yanked releases. // // Names are kept as code writes them after `import newrelic`: the table // writes them bare, and Paths gives each its module. Every row was checked @@ -61,18 +64,21 @@ package members // 7 events. The section's second table, | Legacy Setting | Replacement // Setting |, lists configuration settings (newrelic.ini keys), not members // of the package: only the section's first table is read, so it never is. -var NewRelic11 = Guide{ - API: "newrelic/python-agent", - Package: "newrelic", - Module: "newrelic", - Release: "11.0.0", - DocsRef: "f0b4f817bf9a7b76a78e26609369a8a7ce764c8e", - Repo: "newrelic/docs-website", - Path: "src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx", - Section: "Removed features", - Format: FormatMarkdown, - Header: "Legacy API", - Doc: "release notes", +// +// Paths and DropIns were checked against 11.0.0's table. A later major's +// rows with one replacement are removed_symbol unless listed in DropIns, so +// a new note is read conservatively. +var NewRelic = Guide{ + API: "newrelic/python-agent", + Package: "newrelic", + Module: "newrelic", + Untagged: true, + Repo: "newrelic/docs-website", + Path: "src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-{major}0000.mdx", + Section: "Removed features", + Format: FormatMarkdown, + Header: "Legacy API", + Doc: "release notes", // The cells link to docs.newrelic.com by path ("/docs/agents/…"). LinkBase: "https://docs.newrelic.com", Paths: map[string]string{ diff --git a/plugins/migrationguide/members/newrelic_test.go b/plugins/migrationguide/members/newrelic_test.go index 6cd0c2c..4be8e3e 100644 --- a/plugins/migrationguide/members/newrelic_test.go +++ b/plugins/migrationguide/members/newrelic_test.go @@ -19,7 +19,7 @@ import ( const newrelicSource = "testdata/python-agent-110000-f0b4f817.mdx" func TestNewRelicRegistersItself(t *testing.T) { - kittest.Registered(t, migrationguide.Plugin{Guide: NewRelic11}) + kittest.Registered(t, migrationguide.Plugin{Guide: NewRelic}) } // The golden test: the saved excerpt in, every event out. @@ -81,7 +81,7 @@ func TestNewRelicEachRowOfTheTable(t *testing.T) { } // Every DropIns entry is a member the table removes: a typo would quietly // turn its rename into a removal. - for _, d := range NewRelic11.DropIns { + for _, d := range NewRelic.DropIns { if got[d].change != event.PackageRenamedSymbol { t.Errorf("DropIns %q: not a rename (%+v)", d, got[d]) } @@ -101,7 +101,7 @@ func TestNewRelicDropsWhatIsNotARemovedMember(t *testing.T) { page := string(kittest.Read(t, newrelicSource)) // The lambda row: read, and dropped. - rs, err := Parse([]byte(page), NewRelic11) + rs, err := Parse([]byte(page), NewRelic) if err != nil { t.Fatal(err) } @@ -119,7 +119,7 @@ func TestNewRelicDropsWhatIsNotARemovedMember(t *testing.T) { if asList == page { t.Fatal("no lambda row in the saved release note") } - if names := readNames(t, asList, NewRelic11); !slices.Contains(names, "lambda_handler") || !slices.Contains(names, "LambdaHandlerWrapper") { + if names := readNames(t, asList, NewRelic); !slices.Contains(names, "lambda_handler") || !slices.Contains(names, "LambdaHandlerWrapper") { t.Errorf("with \"and\", the lambda row reads as %v: its drop proves nothing", names) } @@ -132,7 +132,7 @@ func TestNewRelicDropsWhatIsNotARemovedMember(t *testing.T) { if start < 0 || end < start { t.Fatal("the saved release note's shape changed") } - g := NewRelic11 + g := NewRelic g.Header = "Legacy Setting" settings, err := Parse([]byte(page[:start]+page[end:]), g) if err != nil { @@ -190,12 +190,12 @@ func TestDropInsLimitsRenames(t *testing.T) { "| `old_a` | [`new_a`](/a) |", "| `old_b` | `new_b` |", }, "\n") - g := Guide{API: "acme/sdk", Package: "acme", Module: "acme", Release: "2.0.0", Repo: "acme/acme", Path: "MIGRATION.md", + g := Guide{API: "acme/sdk", Package: "acme", Module: "acme", Repo: "acme/acme", Path: "MIGRATION.md", Section: "Removed", Format: FormatMarkdown, Header: "Removed", Paths: map[string]string{"old_a": "mod.old_a", "new_a": "mod.new_a"}} run := func(g Guide) map[string]string { out := map[string]string{} - for _, e := range release(t, g, writeTemp(t, page), "1.0.0") { + for _, e := range release(t, g, writeTemp(t, page), "1.9.0", "2.0.0") { out[e.Subject.Symbols[0]] = string(e.Subject.Change) + " " + e.Subject.Replacement } return out @@ -237,7 +237,7 @@ func readNames(t *testing.T, page string, g Guide) []string { // the saved excerpt. func newrelicIngest(t *testing.T) []event.Event { t.Helper() - return release(t, NewRelic11, newrelicSource, "10.17.0") + return release(t, NewRelic, newrelicSource, "10.17.0", "11.0.0") } // The hint is shown in a pull request or an issue, where a site-relative link diff --git a/plugins/migrationguide/members/posthog.go b/plugins/migrationguide/members/posthog.go index c22c1f3..162271e 100644 --- a/plugins/migrationguide/members/posthog.go +++ b/plugins/migrationguide/members/posthog.go @@ -1,7 +1,9 @@ package members -// PostHog8 is the posthog Python SDK's guide to 8.0.0, -// docs/migration-7.x-to-8.0.md at tag posthog-v8.0.0 (commit +// PostHog is the posthog Python SDK's guide to a major, +// docs/migration-{prev}.x-to-{major}.0.md at the major's first tag. The one +// there is so far (checked 2026-11-20) is 8.0.0's, docs/migration-7.x-to-8.0.md +// at tag posthog-v8.0.0 (commit // 6edff41425188056e48f6119457dc9bc0669ca99), and its "Fix removed APIs" // table: "8.x.x removes these options and APIs". The guide isn't in the repo // at posthog-v7.91.4, the release before, and is unchanged at posthog-v8.0.2. @@ -55,14 +57,18 @@ package members // 7 events. The guide's other tables (endpoints, AI lane arguments, error // fields, retries, dropped events, options, and "Rename deprecated settings", // whose old names still work) aren't under the heading, so they're never read. -var PostHog8 = Guide{ +// +// Paths, EnvVars and StillWork were checked against 8.0.0's table; a later +// major's names that aren't in them are read as the table writes them, and +// NewReplacements keeps every row with one replacement a removed_symbol (no +// rename the client would apply), so a new guide is read conservatively. +var PostHog = Guide{ API: "posthog/python-sdk", Package: "posthog", Module: "posthog", - Release: "8.0.0", TagPrefix: "posthog-v", Repo: "PostHog/posthog-python", - Path: "docs/migration-7.x-to-8.0.md", + Path: "docs/migration-{prev}.x-to-{major}.0.md", Section: "Fix removed APIs", Format: FormatMarkdown, Header: "Removed", @@ -76,6 +82,7 @@ var PostHog8 = Guide{ StillWork: map[string]string{ "capture_mode": `the guide's "Rename deprecated settings" table: posthog.capture_mode still works or has no effect in 8.x.x`, }, - // Every replacement in the table is new in 8.0.0. + // Every replacement in 8.0.0's table is new in 8.0.0; for a later major, + // a rename isn't known to be a drop-in until someone checks. NewReplacements: true, } diff --git a/plugins/migrationguide/members/posthog_test.go b/plugins/migrationguide/members/posthog_test.go index a140ae3..229ab76 100644 --- a/plugins/migrationguide/members/posthog_test.go +++ b/plugins/migrationguide/members/posthog_test.go @@ -18,7 +18,7 @@ import ( const posthogSource = "testdata/migration-7.x-to-8.0-posthog-v8.0.0.md" func TestPostHogRegistersItself(t *testing.T) { - kittest.Registered(t, migrationguide.Plugin{Guide: PostHog8}) + kittest.Registered(t, migrationguide.Plugin{Guide: PostHog}) } // The golden test: the saved guide in, every event out. @@ -85,7 +85,7 @@ func TestPostHogDropsWhatIsNotARemovedMember(t *testing.T) { // The table's own rows: an environment variable, an argument value, and // two rows of prose (a parameter, a dependency). With the rules off, each // is a row of the table, with names in code spans. - rs, err := Parse(kittest.Read(t, posthogSource), PostHog8) + rs, err := Parse(kittest.Read(t, posthogSource), PostHog) if err != nil { t.Fatal(err) } @@ -131,7 +131,7 @@ func TestPostHogDropsWhatIsNotARemovedMember(t *testing.T) { {"Update error handling", "Field", "drops"}, {"Move to event options", "Option", "cookieless_mode"}, } { - g := PostHog8 + g := PostHog g.Section, g.Header = other.section, other.header rs, err := Parse(kittest.Read(t, posthogSource), g) if err != nil { @@ -243,5 +243,5 @@ func TestMarkdownTable(t *testing.T) { // the saved guide. func posthogIngest(t *testing.T) []event.Event { t.Helper() - return release(t, PostHog8, posthogSource, "7.91.4") + return release(t, PostHog, posthogSource, "7.91.4", "8.0.0") } diff --git a/plugins/migrationguide/members/registered_test.go b/plugins/migrationguide/members/registered_test.go index 750b03f..d405937 100644 --- a/plugins/migrationguide/members/registered_test.go +++ b/plugins/migrationguide/members/registered_test.go @@ -10,5 +10,5 @@ import ( ) func TestRegistersItself(t *testing.T) { - kittest.Registered(t, migrationguide.Plugin{Guide: NumPy2}) + kittest.Registered(t, migrationguide.Plugin{Guide: NumPy}) } diff --git a/plugins/migrationguide/members/testdata/README.md b/plugins/migrationguide/members/testdata/README.md index 12bc3cf..f28767c 100644 --- a/plugins/migrationguide/members/testdata/README.md +++ b/plugins/migrationguide/members/testdata/README.md @@ -8,3 +8,5 @@ The golden files, `../../testdata/golden/{numpy-2.0.0,posthog-8.0.0,newrelic-11. | `migration-7.x-to-8.0-posthog-v8.0.0.md` | https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md (commit 6edff41425188056e48f6119457dc9bc0669ca99) | 2026-11-19 | MIT (the repo's LICENSE is the MIT text, with two copyright lines, so GitHub's detector says NOASSERTION; PyPI says MIT), kept whole, byte for byte | "8.x.x removes these options and APIs:" (Fix removed APIs), with rows such as "\| `CaptureV1Error` \| `CaptureError` \|" | | `python-agent-110000-f0b4f817.mdx` | https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx (the repo has no tags; the file's latest commit) | 2026-11-19 | Excerpt for testing; © New Relic, CC BY-NC-SA 4.0. Kept: the "## Removed features" heading, the bullets that introduce its two tables, the "Legacy API" table and the "Legacy Setting" table (lines 30-31 and 36-66 of 136), every line unchanged. Left out: the front matter, "Notes", the Python 3.7 bullet, and the "Deprecated features", "New features", "Bug fixes" and "Support statement" sections. The plugin finds the same 8 rows and 7 events in the excerpt as in the full file | "The following APIs have been removed:", with rows such as "\| `record_exception` \| [`notice_error()`](/docs/agents/python-agent/python-agent-api/notice_error) \|" | | `pypi-numpy-excerpt.json` | https://pypi.org/pypi/numpy/json (shape only) | written for the test, 2026-11-20 | not a saved copy: four releases in the shape of PyPI's JSON API (`releases` → files with `upload_time_iso_8601`, `yanked`), dates approximate, a pre-release among them | for the version-listing test only (ListVersions, consecutive pairs); no golden reads it | +| `github-commits-python-agent-110000.json` | https://api.github.com/repos/newrelic/docs-website/commits?path=src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx&per_page=1 (shape only) | written for the test, 2026-11-20 | not a saved copy: GitHub's commit list cut to the one field read (`sha`), naming the commit the note above was fetched at | for the guide's ref: the newest commit that changed the note | +| `github-commits-none.json` | the same request for a major with no note (shape only) | written for the test, 2026-11-20 | GitHub's answer for a path no commit changed: an empty list | for the "no guide, nothing to read" test | diff --git a/plugins/migrationguide/members/testdata/github-commits-none.json b/plugins/migrationguide/members/testdata/github-commits-none.json new file mode 100644 index 0000000..fe51488 --- /dev/null +++ b/plugins/migrationguide/members/testdata/github-commits-none.json @@ -0,0 +1 @@ +[] diff --git a/plugins/migrationguide/members/testdata/github-commits-python-agent-110000.json b/plugins/migrationguide/members/testdata/github-commits-python-agent-110000.json new file mode 100644 index 0000000..c6b44e0 --- /dev/null +++ b/plugins/migrationguide/members/testdata/github-commits-python-agent-110000.json @@ -0,0 +1 @@ +[{"sha": "f0b4f817bf9a7b76a78e26609369a8a7ce764c8e"}] diff --git a/plugins/migrationguide/members/versions_test.go b/plugins/migrationguide/members/versions_test.go index 1665e9a..42ac3cf 100644 --- a/plugins/migrationguide/members/versions_test.go +++ b/plugins/migrationguide/members/versions_test.go @@ -2,11 +2,14 @@ package members_test import ( "context" + "errors" "fmt" "strings" "testing" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/core/versions" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide" @@ -18,15 +21,15 @@ import ( func TestOnlyTheGuidesReleaseHasEvents(t *testing.T) { env := kittest.Env(t, kittest.Pages{ "https://pypi.org/pypi/numpy/json": "testdata/pypi-numpy-excerpt.json", - NumPy2.URL(): "testdata/numpy_2_0_migration_guide-v2.0.0.rst", + NumPy.RawURL("v2.0.0", 2): "testdata/numpy_2_0_migration_guide-v2.0.0.rst", }) - p := migrationguide.Plugin{Guide: NumPy2} + p := migrationguide.Plugin{Guide: NumPy} ctx := context.Background() vs, err := p.ListVersions(ctx, env) if err != nil { t.Fatal(err) } - pinned := release(t, NumPy2, "testdata/numpy_2_0_migration_guide-v2.0.0.rst", "1.26.4") + pinned := release(t, NumPy, "testdata/numpy_2_0_migration_guide-v2.0.0.rst", "1.26.4", "2.0.0") var got []string for _, pair := range versions.Pairs(vs) { from, err := p.ReadAt(ctx, env, pair[0]) @@ -54,11 +57,41 @@ func TestOnlyTheGuidesReleaseHasEvents(t *testing.T) { } } -// Each release's ref follows the guide's tag shape. -func TestTagsFollowTheGuide(t *testing.T) { - for g, want := range map[*Guide]string{&NumPy2: "v2.0.0", &PostHog8: "posthog-v8.0.0", &NewRelic11: "f0b4f817bf9a7b76a78e26609369a8a7ce764c8e"} { - if got := g.Tag(); got != want { - t.Errorf("%s: tag %q, want %q", g.Package, got, want) +// Each guide is read where its package publishes it: at the major's first +// tag (TagPrefix + version), or, for a docs repo with no tags, at the newest +// commit that changed the major's note. +func TestEachGuideIsReadWhereItsPublished(t *testing.T) { + ctx := context.Background() + for _, c := range []struct { + g Guide + rel string + want string + }{ + {NumPy, "2.0.0", "https://raw.githubusercontent.com/numpy/numpy/v2.0.0/doc/source/numpy_2_0_migration_guide.rst"}, + {PostHog, "8.0.0", "https://raw.githubusercontent.com/PostHog/posthog-python/posthog-v8.0.0/docs/migration-7.x-to-8.0.md"}, + {NewRelic, "11.0.0", "https://raw.githubusercontent.com/newrelic/docs-website/" + newrelicCommit + "/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx"}, + } { + got, err := c.g.GuideURL(ctx, guideEnv(t, c.g, "testdata/README.md", c.rel), plugin.Version{ID: c.rel}) + if err != nil || got != c.want { + t.Errorf("%s %s: %q, %v; want %q", c.g.Package, c.rel, got, err, c.want) + } + if got, err := c.g.GuideURL(ctx, plugin.Env{}, plugin.Version{ID: c.rel[:len(c.rel)-1] + "1"}); got != "" || err != nil { + t.Errorf("%s: a release that isn't a major's first has no guide: %q, %v", c.g.Package, got, err) } } } + +// A major with no guide has nothing to read: a 404 at its tag, or (docs +// repo) no commit ever changed its note's path. The pair is skipped, not +// failed, and not a release without changes. +func TestAMajorWithNoGuideHasNothingToRead(t *testing.T) { + ctx := context.Background() + env := kittest.Env(t, kittest.Pages{NewRelic.CommitsURL(14): "testdata/github-commits-none.json"}) + if _, err := (migrationguide.Plugin{Guide: NewRelic}).ReadAt(ctx, env, plugin.Version{ID: "14.0.0"}); !errors.Is(err, plugin.ErrNothingToRead) { + t.Errorf("no commit for the note: %v, want plugin.ErrNothingToRead", err) + } + notFound := plugin.Env{Get: func(context.Context, string) ([]byte, error) { return nil, &fetch.StatusError{StatusCode: 404} }} + if _, err := (migrationguide.Plugin{Guide: NumPy}).ReadAt(ctx, notFound, plugin.Version{ID: "3.0.0"}); !errors.Is(err, plugin.ErrNothingToRead) { + t.Errorf("no guide at the tag: %v, want plugin.ErrNothingToRead", err) + } +} diff --git a/plugins/migrationguide/migrationguide.go b/plugins/migrationguide/migrationguide.go index df864b6..fa95a49 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -13,10 +13,12 @@ package migrationguide import ( "context" + "errors" "fmt" "time" "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/members" "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" @@ -37,30 +39,30 @@ func init() { ID: "numpy", Name: "NumPy", Category: plugin.CategoryPackages, Homepage: "https://numpy.org", Sources: []plugin.Source{{ ID: "numpy", Layer: plugin.LayerPackage, Page: "providers/numpy.md", - Watches: "Members removed or renamed in the main namespace in NumPy 2.0", - URLs: []string{"https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst"}, + Watches: "Members a new major removes or renames in the main namespace, from that major's migration guide at its first tag", + URLs: []string{"https://numpy.org/devdocs/numpy_2_0_migration_guide.html", "https://pypi.org/project/numpy/"}, Packages: []string{"pypi:numpy"}, - Plugin: Plugin{Guide: members.NumPy2}, + Plugin: Plugin{Guide: members.NumPy}, }}, }) plugin.RegisterProvider(plugin.Provider{ ID: "posthog", Name: "PostHog", Category: plugin.CategoryAnalytics, Homepage: "https://posthog.com", Sources: []plugin.Source{{ ID: "python-sdk", Layer: plugin.LayerSDK, Page: "providers/posthog.md", - Watches: "Members removed in the posthog Python SDK 8.0.0", - URLs: []string{"https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md"}, + Watches: "Members a new major of the posthog Python SDK removes, from its migration guide in docs/ at the major's first tag", + URLs: []string{"https://github.com/PostHog/posthog-python/tree/main/docs", "https://pypi.org/project/posthog/"}, Packages: []string{"pypi:posthog"}, - Plugin: Plugin{Guide: members.PostHog8}, + Plugin: Plugin{Guide: members.PostHog}, }}, }) plugin.RegisterProvider(plugin.Provider{ ID: "newrelic", Name: "New Relic", Category: plugin.CategoryMonitoring, Homepage: "https://newrelic.com", Sources: []plugin.Source{{ ID: "python-agent", Layer: plugin.LayerSDK, Page: "providers/newrelic.md", - Watches: "Members removed in the New Relic Python agent 11.0.0", - URLs: []string{"https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx"}, + Watches: "Members a new major of the New Relic Python agent removes, from the major's release notes (Removed features)", + URLs: []string{"https://docs.newrelic.com/docs/release-notes/agent-release-notes/python-release-notes/", "https://pypi.org/project/newrelic/"}, Packages: []string{"pypi:newrelic"}, - Plugin: Plugin{Guide: members.NewRelic11}, + Plugin: Plugin{Guide: members.NewRelic}, }}, }) } @@ -74,13 +76,13 @@ type Guide interface { // Releases are the versions, oldest first, each with the ref its guide // would be read at. Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, error) - // GuideURL is where the guide is at v, pinned to v's tag, or "" when v - // has no guide (a release that isn't a new major). - GuideURL(v plugin.Version) string - // Read turns the guide, as read at to, into events with + // GuideURL is where the guide is at v, pinned to v's tag (or a commit), + // or "" when v has no guide (a release that isn't a new major). + GuideURL(ctx context.Context, env plugin.Env, v plugin.Version) (string, error) + // Read turns the guide, as read at to from sourceURL, into events with // previous_version from, and the rows that failed to become events. err // is a guide it can't read. - Read(page []byte, from, to plugin.Version, now time.Time) (events []event.Event, rejected []error, err error) + Read(page []byte, sourceURL string, from, to plugin.Version, now time.Time) (events []event.Event, rejected []error, err error) } // Plugin reads one source's migration guide. @@ -96,13 +98,22 @@ func (p Plugin) ListVersions(ctx context.Context, env plugin.Env) ([]plugin.Vers } // ReadAt fetches the guide at v; a release with no guide reads as nothing (a -// snapshot with no content). +// snapshot with no content). A new major whose guide isn't there (a 404 at +// its tag) has nothing to read: plugin.ErrNothingToRead, so the pair is +// kept as skipped, not as a failure, nor as a release with no changes. func (p Plugin) ReadAt(ctx context.Context, env plugin.Env, v plugin.Version) (plugin.Snapshot, error) { - url := p.Guide.GuideURL(v) + url, err := p.Guide.GuideURL(ctx, env, v) + if err != nil { + return plugin.Snapshot{}, err + } if url == "" { return plugin.Snapshot{Version: v}, nil } page, err := env.Get(ctx, url) + var se *fetch.StatusError + if errors.As(err, &se) && se.StatusCode == 404 { + return plugin.Snapshot{}, fmt.Errorf("no guide at %s: %w", url, plugin.ErrNothingToRead) + } if err != nil { return plugin.Snapshot{}, fmt.Errorf("fetching %s: %w", url, err) } @@ -115,7 +126,7 @@ func (p Plugin) Extract(_ context.Context, env plugin.Env, from, to plugin.Snaps if to.Content == nil { return plugin.Result{}, nil } - events, rejected, err := p.Guide.Read(to.Content, from.Version, to.Version, env.Now().UTC()) + events, rejected, err := p.Guide.Read(to.Content, to.SourceURL, from.Version, to.Version, env.Now().UTC()) if err != nil { return plugin.Result{}, fmt.Errorf("reading %s: %w", to.SourceURL, err) } diff --git a/plugins/migrationguide/migrationguide_test.go b/plugins/migrationguide/migrationguide_test.go index 4b7badc..c193d15 100644 --- a/plugins/migrationguide/migrationguide_test.go +++ b/plugins/migrationguide/migrationguide_test.go @@ -3,15 +3,13 @@ package migrationguide import ( "strings" "testing" - - "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) func TestAMigrationGuideStoresOneEventPerRemovedParameter(t *testing.T) { // Only the v1.0.0 tag is saved: fetching anything else fails the test, and // kittest's second extract of the pair must store nothing new. var params []string - for _, e := range anthropicV1(t, sdkguide.AnthropicV1) { + for _, e := range anthropicV1(t, anthropicGuideV1) { params = append(params, e.Subject.Parameter) } if strings.Join(params, ",") != "temperature,top_p,top_k" { diff --git a/plugins/migrationguide/registered_test.go b/plugins/migrationguide/registered_test.go index acd1ca5..3b659bb 100644 --- a/plugins/migrationguide/registered_test.go +++ b/plugins/migrationguide/registered_test.go @@ -4,9 +4,8 @@ import ( "testing" "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) func TestRegistersItself(t *testing.T) { - kittest.Registered(t, Plugin{Guide: sdkguide.AnthropicV1}) + kittest.Registered(t, Plugin{Guide: anthropicGuideV1}) } diff --git a/plugins/migrationguide/sdkguide/pinned_test.go b/plugins/migrationguide/sdkguide/pinned_test.go new file mode 100644 index 0000000..f914705 --- /dev/null +++ b/plugins/migrationguide/sdkguide/pinned_test.go @@ -0,0 +1,5 @@ +package sdkguide + +// AnthropicV1 is anthropic-sdk-python's guide to 1.0.0: what the tests pin. +// Only a test names a release. +var AnthropicV1 = Anthropic.At(1) diff --git a/plugins/migrationguide/sdkguide/sdkguide.go b/plugins/migrationguide/sdkguide/sdkguide.go index ddf9219..cc02580 100644 --- a/plugins/migrationguide/sdkguide/sdkguide.go +++ b/plugins/migrationguide/sdkguide/sdkguide.go @@ -47,9 +47,6 @@ var Anthropic = Guide{ Symbols: []string{"messages.create", "messages.stream", "messages.parse"}, } -// AnthropicV1 is anthropic-sdk-python's guide to 1.0.0: what the golden pins. -var AnthropicV1 = Anthropic.At(1) - // At is g pinned to one major. func (g Guide) At(major int) Guide { g.Major = major diff --git a/plugins/migrationguide/sdkguide/versions.go b/plugins/migrationguide/sdkguide/versions.go index 20aa99e..7a7f5fe 100644 --- a/plugins/migrationguide/sdkguide/versions.go +++ b/plugins/migrationguide/sdkguide/versions.go @@ -2,7 +2,6 @@ package sdkguide import ( "context" - "fmt" "time" "github.com/patch-it-dev/patch-it-plugins/core/event" @@ -34,16 +33,17 @@ func (g Guide) Releases(ctx context.Context, env plugin.Env) ([]plugin.Version, // GuideURL is the guide at v's tag when v is the first release of its major // (X.0.0): only a new major has a guide to read. Any other release has none // (""). -func (g Guide) GuideURL(v plugin.Version) string { - if !FirstOfMajor(v.ID) { - return "" +func (g Guide) GuideURL(_ context.Context, _ plugin.Env, v plugin.Version) (string, error) { + if !versions.FirstOfMajor(v.ID) { + return "", nil } - return g.At(versions.Major(v.ID)).URL() + return g.At(versions.Major(v.ID)).URL(), nil } // Read is an event per parameter the to major removed, read from its -// guide, with previous_version from's release. -func (g Guide) Read(page []byte, from, to plugin.Version, now time.Time) (_ []event.Event, rejected []error, err error) { +// guide (at the major's tag: sourceURL), with previous_version from's +// release. +func (g Guide) Read(page []byte, _ string, from, to plugin.Version, now time.Time) (_ []event.Event, rejected []error, err error) { g = g.At(versions.Major(to.ID)) removals, err := Parse(page, g) if err != nil { @@ -52,9 +52,3 @@ func (g Guide) Read(page []byte, from, to plugin.Version, now time.Time) (_ []ev events, errs := Events(g, removals, from.ID, now) return events, errs, nil } - -// FirstOfMajor is true for X.0.0, the release a major's guide is tagged at. -func FirstOfMajor(v string) bool { - m := versions.Major(v) - return m > 0 && v == fmt.Sprintf("%d.0.0", m) -} diff --git a/plugins/migrationguide/versions_test.go b/plugins/migrationguide/versions_test.go index 7a10faf..9a39cd5 100644 --- a/plugins/migrationguide/versions_test.go +++ b/plugins/migrationguide/versions_test.go @@ -17,7 +17,7 @@ import ( func TestOnlyANewMajorHasAGuide(t *testing.T) { env := kittest.Env(t, kittest.Pages{ "https://pypi.org/pypi/anthropic/json": "testdata/pypi-anthropic-excerpt.json", - sdkguide.AnthropicV1.URL(): "sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md", + anthropicGuideV1.URL(): "sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md", }) p := Plugin{Guide: sdkguide.Anthropic} ctx := context.Background() diff --git a/providers/newrelic.md b/providers/newrelic.md index 9e87fc3..a014f70 100644 --- a/providers/newrelic.md +++ b/providers/newrelic.md @@ -2,13 +2,13 @@ ## What it watches -Functions and classes removed from New Relic's Python agent (the `newrelic` package) in 11.0.0: `newrelic.agent.record_exception`, `newrelic.agent.add_custom_parameter`, `newrelic.api.log.NewRelicLogHandler`, and others. Code that uses one breaks on the upgrade. The plugin emits one event per member, pinned to that release. +Functions and classes a new major of New Relic's Python agent (the `newrelic` package) removes, from the major's release notes: in 11.0.0, `newrelic.agent.record_exception`, `newrelic.agent.add_custom_parameter`, `newrelic.api.log.NewRelicLogHandler`, and others. Code that uses one breaks on the upgrade. One event per member, with the major's first release as `version` and the release before it on PyPI as `previous_version`. The releases are listed from PyPI (yanked ones included: 11.0.0 is yanked); nothing in the code names a release or a commit. Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members reader (`plugins/migrationguide/members`), reading a Markdown table. ## Why this source -- **Source:** [`python-agent-110000.mdx`](https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx) in newrelic/docs-website at commit `f0b4f817bf9a7b76a78e26609369a8a7ce764c8e` (2026-04-22, the file's latest commit). The plugin reads the raw file at that commit, because the repo has no tags. Checked on 2026-11-19. © New Relic, CC BY-NC-SA 4.0. +- **Source:** `python-agent-0000.mdx` in newrelic/docs-website (9.0.0 to 13.0.0 are there, checked 2026-11-20), for each major's first release. The repo has no tags, so the plugin asks GitHub for the newest commit that changed the note and reads the raw file at that commit. 11.0.0's, [`python-agent-110000.mdx`](https://github.com/newrelic/docs-website/blob/f0b4f817bf9a7b76a78e26609369a8a7ce764c8e/src/content/docs/release-notes/agent-release-notes/python-release-notes/python-agent-110000.mdx) at commit `f0b4f817` (2026-04-22), is the one checked on 2026-11-19. A note with no "Removed features" section, or no note, has nothing to read (the pair is skipped). © New Relic, CC BY-NC-SA 4.0. - **Why this one:** these are New Relic's own release notes for the agent's 11.0.0. Their "Removed features" section has a table of the APIs that 11.0.0 removed, with what to use instead. A commit never changes, so the URL is its own citation. 11.0.0 is a version a repo pins. - **Alternatives considered:** - **The REST API v2 spec**, (OpenAPI 3.0.1, 58 operations on 43 paths, fetched 2026-11-19). New Relic serves it only live and doesn't commit it anywhere, so there's no release to pin or replay. Its deprecations aren't machine-readable: it has 0 `deprecated: true` flags. Instead, 12 operation descriptions say "This endpoint will be deprecated after", 11 of them "2024/01" and 1 "2027/01". New Relic's own end-of-life notice for REST API v2 (below) contradicts those dates for 10 of the 12: it retires them on 2027-07-31. It keeps the other 2, on `/alerts_location_failure_conditions/policies/*`, as "Not impacted". @@ -51,4 +51,6 @@ Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members read - **The same functions reached another way** get no event: the `newrelic.api.transaction` and `newrelic.api.time_trace` definitions, and the methods of the same names on `Transaction` (`add_custom_parameter`, `record_exception`…). All were removed in 11.0.0 too. - **The removed settings** (`ssl`, `error_collector.ignore_errors`, `strip_exception_messages.whitelist`…). They're configuration, not code, and change events have no subject for them. - New Relic's REST API v2 end of life (2027-07-31) and NerdGraph (see above). -- New Relic's other agents, and later majors of the Python agent: each is a new entry in this plugin. +- New Relic's other agents. +- Removals in a minor release: only a major's note is read. +- A later major's table is read with 11.0.0's `Paths` and `DropIns`: a name not in them is written as the table writes it, and only a listed drop-in is a rename. diff --git a/providers/numpy.md b/providers/numpy.md index 32357a6..b16e8d9 100644 --- a/providers/numpy.md +++ b/providers/numpy.md @@ -2,13 +2,13 @@ ## What it watches -Members removed from or renamed in NumPy's main namespace in 2.0.0 (`np.float_`, `np.NaN`, `np.product` and about fifty more): code using one raises `AttributeError`. One event per member. Pinned to that release. +Members a new major removes from or renames in NumPy's main namespace, from that major's migration guide: in 2.0.0, `np.float_`, `np.NaN`, `np.product` and about fifty more (code using one raises `AttributeError`). One event per member, with the major's first release as `version` and the release before it on PyPI as `previous_version`. The releases are listed from PyPI; the guide is read at each major's first tag (`v.0.0`), so nothing in the code names a release. Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members reader (`plugins/migrationguide/members`). ## Why this source -- **Source:** [`doc/source/numpy_2_0_migration_guide.rst` at v2.0.0](https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst), read raw at the tag. Checked on 2026-11-04. +- **Source:** `doc/source/numpy__0_migration_guide.rst` at tag `v.0.0`, read raw at the tag; the one so far is [2.0's](https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst). A major with no guide at its tag has nothing to read (the pair is skipped). Releases from [PyPI](https://pypi.org/project/numpy/). Checked on 2026-11-04 (2.0) and 2026-11-20 (no other guide yet). - **Why this one:** it's NumPy's own migration guide, with a table of every removed member and its migration guideline. A tag never changes, so the URL is its own citation. - **Alternatives considered:** the 2.0.0 release notes (list the removals in prose, spread over several sections); the rendered guide on numpy.org (the same text as HTML); NEP 52 (the plan, not what shipped). - **Quote:** "The table below provides replacements for the removed members:" (Main namespace), with rows such as "NaN — Use ``np.nan`` instead." @@ -27,4 +27,5 @@ Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members read ## Known gaps - The guide's other tables (`np.lib` members, changed behavior) aren't read. -- Later releases' removals aren't watched. +- Removals in a minor release aren't watched: only a major gets a guide. +- A later major's guide is read with 2.0's rule: a guideline that is exactly "Use ``np.`` instead." is a rename. NumPy 2.0's guide says each such replacement works on 1.x; a later guide might name one that's new, which would make the rename fail on the release before. diff --git a/providers/posthog.md b/providers/posthog.md index 917620c..9e6fc84 100644 --- a/providers/posthog.md +++ b/providers/posthog.md @@ -2,13 +2,13 @@ ## What it watches -Members removed from the `posthog` Python SDK in 8.0.0 (`CaptureMode`, `posthog.capture_v1`, `posthog.capture_v1.CaptureV1Error`, `posthog.request.batch_post`…): code using one breaks on the upgrade. One event per member. Pinned to that release. +Members a new major of the `posthog` Python SDK removes, from that major's migration guide: in 8.0.0, `CaptureMode`, `posthog.capture_v1`, `posthog.capture_v1.CaptureV1Error`, `posthog.request.batch_post`… (code using one breaks on the upgrade). One event per member, with the major's first release as `version` and the release before it on PyPI as `previous_version`. The releases are listed from PyPI; the guide is read at each major's first tag, so nothing in the code names a release. Kind: `migrationguide` (`plugins/migrationguide`), with the removed-members reader (`plugins/migrationguide/members`), reading a Markdown table. ## Why this source -- **Source:** [`docs/migration-7.x-to-8.0.md` at posthog-v8.0.0](https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md) (commit `6edff41425188056e48f6119457dc9bc0669ca99`), read raw at the tag. Checked on 2026-11-19. The guide isn't in the repo at posthog-v7.91.4, the release before, and is the same at posthog-v8.0.2. MIT. +- **Source:** `docs/migration-.x-to-.0.md` at tag `posthog-v.0.0`, read raw at the tag; the one so far is [`docs/migration-7.x-to-8.0.md` at posthog-v8.0.0](https://github.com/PostHog/posthog-python/blob/posthog-v8.0.0/docs/migration-7.x-to-8.0.md) (commit `6edff41425188056e48f6119457dc9bc0669ca99`). A major with no guide at its tag has nothing to read (the pair is skipped). Releases from [PyPI](https://pypi.org/project/posthog/). Checked on 2026-11-19. The guide isn't in the repo at posthog-v7.91.4, the release before, and is the same at posthog-v8.0.2. MIT. - **Why this one:** it's PostHog's own migration guide for the SDK's 8.0.0, and its "Fix removed APIs" section is a table of what 8.0.0 removed and what to use instead. A tag never changes, so the URL is its own citation, and 8.0.0 is a version a repo pins. - **Alternatives considered:** - **`references/public_api_snapshot.txt`** in the same repo: a generated listing of the public API at every tag. Diffing it between two releases gives every removed name with its full path, but no reason, replacement or announcement. The plugin reads the guide, and the listing was used to check the paths of the guide's names.