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
94 changes: 53 additions & 41 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 Expand Up @@ -421,40 +427,46 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.Event {
defDir: "plugins/catalog",
def: `package catalog

// {{.Ident}} is {{.Provider}}'s catalog: one JSON object, one key per command
// or endpoint, at a git ref.
import "regexp"

// {{.Ident}} is {{.Provider}}'s command catalog: one JSON file per command in a
// directory of its repo, read at each release tag, as Redis's is (redis.go).
//
// ` + todo + `: the ecosystem and package for the events' subject, the repo,
// the catalog's path and the commits API URL for the newest ref. Say what you
// checked, with the date, as catalog.go does for Redis.
var {{.Ident}} = Catalog{
// the directory and the release tags' shape. Say what you checked, with the
// date, as redis.go does for Redis.
var {{.Ident}} = Commands{
API: "{{.ID}}", Ecosystem: "{{.ProviderID}}", Package: "{{.ProviderID}}",
Repo: "TODO-owner/TODO-repo", Path: "TODO/commands.json",
RefsURL: "https://api.github.com/repos/TODO-owner/TODO-repo/commits/main",
Repo: "TODO-owner/TODO-repo", Dir: "TODO/commands",
Release: regexp.MustCompile(` + "`" + `^v?(\d+\.\d+\.\d+)$` + "`" + `),
}
`,
register: `plugin.Register(Plugin{Catalog: {{.Ident}}})`,
pluginOf: `Plugin{Catalog: {{.Ident}}}`,
register: `plugin.Register({{.Ident}})`,
pluginOf: `{{.Ident}}`,
fixtures: map[string]string{
"{{.File}}-old.json": "{\"PLACEHOLDER\": {}}\n",
"{{.File}}-new.json": "{\"PLACEHOLDER\": {}}\n",
"{{.File}}-old.json": "[{\"name\": \"placeholder.json\", \"type\": \"file\"}, {\"name\": \"kept.json\", \"type\": \"file\"}]\n",
"{{.File}}-new.json": "[{\"name\": \"kept.json\", \"type\": \"file\"}]\n",
"{{.File}}-placeholder.json": "{\"PLACEHOLDER\": {\"summary\": \"a placeholder\"}}\n",
},
source: "{{.File}}-new.json",
ingest: `// The two refs the saved snapshots are at.
// ` + todo + `: the real commits, oldest first.
dropFile: "[{\"name\": \"placeholder.json\", \"type\": \"file\"}, {\"name\": \"kept.json\", \"type\": \"file\"}, {\"name\": \"added.json\", \"type\": \"file\"}]\n",
source: "{{.File}}-new.json",
ingest: `// The two releases the saved listings are at.
// ` + todo + `: the real tags, oldest first.
const (
{{.Lower}}OldRef = "0000000000000000000000000000000000000000"
{{.Lower}}NewRef = "1111111111111111111111111111111111111111"
{{.Lower}}OldRef = "v1.0.0"
{{.Lower}}NewRef = "v2.0.0"
)

// {{.Lower}}Ingest extracts the change from the saved old snapshot to file.
// {{.Lower}}Ingest is the version pair from the saved old listing to file,
// the newer release's listing; a file gone from it is read at the old tag.
func {{.Lower}}Ingest(t *testing.T, file string) []event.Event {
t.Helper()
env := kittest.Env(t, kittest.Pages{
{{.Ident}}.URL({{.Lower}}OldRef): "testdata/{{.File}}-old.json",
{{.Ident}}.URL({{.Lower}}NewRef): file,
{{.Ident}}.listingURL({{.Lower}}OldRef): "testdata/{{.File}}-old.json",
{{.Ident}}.listingURL({{.Lower}}NewRef): file,
{{.Ident}}.FileURL({{.Lower}}OldRef, "placeholder.json"): "testdata/{{.File}}-placeholder.json",
})
return kittest.Versions(t, env, Plugin{Catalog: {{.Ident}}},
return kittest.Versions(t, env, {{.Ident}},
plugin.Version{ID: {{.Lower}}OldRef, Ref: {{.Lower}}OldRef}, plugin.Version{ID: {{.Lower}}NewRef, Ref: {{.Lower}}NewRef})
}
`,
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)
}
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/which-kind.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Every kind is one of two shapes ([writing-a-plugin.md, step 4](writing-a-plugin.
| Is there a **guide that lists what a release removed**, one per major or per release, in a table? | `migrationguide` | The guide at the release's tag: removed request parameters (reader `sdk`) or removed members of a module (reader `members`, RST or Markdown tables) | `MIGRATION.md` per major; "removed members" tables in a 2.0 migration guide; an API version removal guide |
| Is there a **changelog**: a file per release (`CHANGELOG.md`, `CHANGES.rst`, `HISTORY.rst`), or a machine-readable JSON changelog? | `changelog` | The release's section at its tag (reader `markdown`), or the life-cycle entries a JSON changelog adds commit by commit (reader `json`) | Keep a Changelog files; reStructuredText release notes; an API changelog JSON in a repo; a Terraform provider's changelog |
| Is there a **live page of dated notices**: a deprecations or shutdown table, an end-of-life table, or an **RSS/Atom feed** of announcements? | `notices` | The page as it is now, cited through a Web Archive snapshot, against the snapshot kept from the read before: a living page, with no versions of its own (reader `deprecations`, `feed`, or an end-of-life table) | A model deprecations page; an API end-of-life policy table; a changelog feed with a "deprecation" label; a Kubernetes API removals page |
| Is there a **flat catalog**, one JSON entry per name (a command, an endpoint), with no release tags? | `catalog` | Two snapshots, compared for names that disappeared entirely | A list of commands a server accepts, kept in a repo |
| Is there a **structured catalog** in the provider's repo: one JSON file per command, or one file of upcoming removals? | `catalog` | Each release (or commit) of the catalog, compared with the one before: names that disappeared entirely, or removals newly announced | The command definitions a server is built from, at each release tag |
| Is it a **published package** with no changelog worth reading? | `apisurface` | Each release's files from the registry (PyPI first), compared: removed or renamed classes, functions, methods, and parameters removed or newly required | An SDK generated from a spec, released often, whose changelog says "chore: update types" |

Still no "yes"? Open a [discussion](https://github.com/patch-it-dev/patch-it-plugins/discussions) with the source's link: a new kind is a new package under `plugins/`, and the questions above get one more row.
Expand Down
Loading
Loading