Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 27 additions & 21 deletions cmd/new-plugin/formats.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"},
}
Expand Down Expand Up @@ -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()})
Expand All @@ -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",
}
`,
Expand Down Expand Up @@ -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"},
Expand All @@ -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}}}`,
Expand All @@ -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"
Expand Down
6 changes: 4 additions & 2 deletions core/github/github.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -63,7 +64,8 @@ func LatestRelease(ctx context.Context, get Getter, url string) (string, error)
}

// LatestCommit reads a commit list (url: commits?path=<file>&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 {
Expand All @@ -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)

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.

}
return commits[0].SHA, nil
}
Expand Down
18 changes: 17 additions & 1 deletion core/versions/versions.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 + "/"})
Expand Down Expand Up @@ -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 {
Expand Down
15 changes: 15 additions & 0 deletions core/versions/versions_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 != "[email protected] [email protected] [email protected] [email protected]" {
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) {
Expand Down
2 changes: 1 addition & 1 deletion docs/writing-a-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
56 changes: 56 additions & 0 deletions plugins/all/pins_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
6 changes: 0 additions & 6 deletions plugins/changelog/changelog.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
8 changes: 8 additions & 0 deletions plugins/changelog/pinned_test.go
Original file line number Diff line number Diff line change
@@ -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")
)
8 changes: 6 additions & 2 deletions plugins/migrationguide/golden_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ 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
// patch-it's hosted ingestion service extracts it. 0.75.0 isn't a new major:
// 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
Expand All @@ -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)
3 changes: 2 additions & 1 deletion plugins/migrationguide/members/export_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) }
36 changes: 28 additions & 8 deletions plugins/migrationguide/members/golden_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
}
Loading
Loading