Skip to content
Merged
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
6 changes: 6 additions & 0 deletions site/src/content/docs/versions/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ description: Every kind of entry versions.yaml takes, the build arguments each b
| `today` | today's date |
| `with <name>` | `<name>`'s version, spelled with a `v` only when this entry's is: two files of one release, such as VictoriaMetrics and its vmutils. A bump of `<name>` moves this entry in the same file, and the gate fails while they differ |
| `with <name> pin` | `<name>`'s pin: a file named by another's commit, such as the VS Code server of a VS Code release |
| `with <owner/repo> <name> [pin]` | the same, of `<name>` in that GitHub repository's `versions.yaml` as its default branch has it now, read through the API (`GITHUB_TOKEN` or `GH_TOKEN` for a private one): `check` says when it moved, and a bump takes it. The gate reads no network, so it does not hold this one |
| `follows <name>` | another entry's, by a relation the file cannot compute, or another repository's: `check` reports it for a person to read |

The format only grows. Every repository that uses go-tools reads the same file format, so a field,
Expand Down Expand Up @@ -89,3 +90,8 @@ lists: adding one is an edit, not a bump.
victoriametrics' version and refuses any other. The entry named is one with a track of its own: a
chain of `with` is refused as the file is read, and so is one whose entry is not in it. An entry
with an `archive` is bumped by hand, so it refuses the bump of the entry it is with.

An entry can be with another repository's: spin-ami rebuilds the Grafana spin lays, at the tag spin
pins, so its entry is `with spin-stack/spin grafana`. When spin moves Grafana, spin-ami's
`versions check` says its own is behind, and `versions bump grafana` takes the version spin's file
has, spelled as spin-ami's entry spells its own.
28 changes: 18 additions & 10 deletions versions/gate/gate.go
Original file line number Diff line number Diff line change
Expand Up @@ -81,16 +81,7 @@ func (g Gate) Check() error {
}
// An entry tracked with another is at what that one is at: a bump moves both, and a hand that
// moved one alone has written a build of two releases.
for _, e := range v.Entries {
leader, _, ok := e.With()
if !ok {
continue
}
if want, _ := v.Expected(e); e.Version != want {
errs = append(errs, fmt.Errorf("%s: %s is with %s, so it is at %q, not %q: versions bump %s moves both",
versions.File, e.Name, leader, want, e.Version, leader))
}
}
errs = append(errs, apart(v)...)
used := map[string]bool{}
for _, rel := range slices.Sorted(maps.Keys(files)) {
// A test's digests are fixtures, but what it reads of versions.yaml is read.
Expand Down Expand Up @@ -118,6 +109,23 @@ func (g Gate) Check() error {
return errors.Join(errs...)
}

// apart is each entry tracked with another in the file that is not at that one's version. One with
// another repository's entry is check's: the gate reaches nothing over the network.
func apart(v *versions.Versions) []error {
var errs []error
for _, e := range v.Entries {
a, ok, _ := e.With()
if !ok || a.Repo != "" {
continue
}
if want, _ := v.Expected(e); e.Version != want {
errs = append(errs, fmt.Errorf("%s: %s is with %s, so it is at %q, not %q: versions bump %s moves both",
versions.File, e.Name, a.Name, want, e.Version, a.Name))
}
}
return errs
}

// TaskCommand is the go-tools command a go.mod takes as `go tool task`: Task at versions.yaml's
// `task`, with go-tools' latest release on its PATH.
const TaskCommand = "github.com/spin-stack/go-tools/cmd/task"
Expand Down
4 changes: 4 additions & 0 deletions versions/gate/gate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,10 @@ func TestTheGateSaysWhereAPinIsNotVersionsYAMLs(t *testing.T) {
f[versions.File] += "- name: headers\n kind: download\n source: https://y/{version}\n version: v1\n pin: " + strings.Repeat("d", 64) + "\n track: with kernel\n"
f["Taskfile.yml"] += " - versions args headers\n"
}},
{name: "an entry tracked with another repository's, which is check's to read", change: func(f map[string]string) {
f[versions.File] += "- name: headers\n kind: download\n source: https://y/{version}\n version: '9'\n pin: " + strings.Repeat("d", 64) + "\n track: with spin-stack/spin kernel\n"
f["Taskfile.yml"] += " - versions args headers\n"
}},
{name: "an entry tracked with another, moved alone", change: func(f map[string]string) {
f[versions.File] += "- name: headers\n kind: download\n source: https://y/{version}\n version: '2'\n pin: " + strings.Repeat("d", 64) + "\n track: with kernel\n"
f["Taskfile.yml"] += " - versions args headers\n"
Expand Down
60 changes: 55 additions & 5 deletions versions/upstream/upstream.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import (
"bufio"
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
Expand Down Expand Up @@ -92,7 +93,7 @@ func newest(ctx context.Context, v *versions.Versions, e versions.Entry) (string
case "follows":
return "", fmt.Errorf("%w: %s", errFollows, arg)
case "with":
return v.Expected(e)
return newestWith(ctx, v, e)
}
return "", fmt.Errorf("versions: %s tracks %q, which check does not know", e.Name, e.Track)
}
Expand Down Expand Up @@ -153,10 +154,17 @@ func Bump(ctx context.Context, v *versions.Versions, name, version string) (vers
return versions.Entry{}, nil, fmt.Errorf("versions: %s's archive is what a build's git writes of the commit, so it is bumped by hand: see its note", a.Name)
}
}
if leader, _, ok := e.With(); ok && version != "" {
// Parse refused a with that names no entry, so the expected version is always there.
if want, _ := v.Expected(e); version != want {
return versions.Entry{}, nil, fmt.Errorf("versions: %s is with %s, at %q: bump %s", name, leader, want, leader)
if a, ok, _ := e.With(); ok && version != "" {
want, err := newest(ctx, v, e)
if err != nil {
return versions.Entry{}, nil, err
}
switch {
case version == want:
case a.Repo != "":
return versions.Entry{}, nil, fmt.Errorf("versions: %s is with %s's %s, at %q: it moves when that one does", name, a.Repo, a.Name, want)
default:
return versions.Entry{}, nil, fmt.Errorf("versions: %s is with %s, at %q: bump %s", name, a.Name, want, a.Name)
}
}
if version == "" {
Expand Down Expand Up @@ -318,6 +326,48 @@ func run(ctx context.Context, name string, args ...string) (string, error) {
return string(out), nil
}

// newestWith is what an entry tracked with another is at: that one's, in v or in its repository's
// file as it is now.
func newestWith(ctx context.Context, v *versions.Versions, e versions.Entry) (string, error) {
a, _, err := e.With()
switch {
case err != nil: // mutate-exempt: Parse refused a with track of no form, and v is parsed
return "", err
case a.Repo == "":
return v.Expected(e)
}
other, err := repositoryFile(ctx, a.Repo)
if err != nil {
return "", err
}
return versions.ExpectedIn(e, other)
}

// repositoryFile is the versions.yaml at the default branch of a GitHub repository, owner/repo,
// read through the API so that GITHUB_TOKEN or GH_TOKEN reaches a private one: what that
// repository pins now, which a release of it made later will carry.
func repositoryFile(ctx context.Context, repo string) (*versions.Versions, error) {
var file struct {
Content string `json:"content"`
Encoding string `json:"encoding"`
}
if err := getJSON(ctx, "https://api.github.com/repos/"+repo+"/contents/"+versions.File, &file); err != nil {
return nil, fmt.Errorf("%w (a private repository is read with GITHUB_TOKEN or GH_TOKEN)", err)
}
if file.Encoding != "base64" {
return nil, fmt.Errorf("versions: %s's %s came as %q, not base64", repo, versions.File, file.Encoding)
}
raw, err := base64.StdEncoding.DecodeString(strings.ReplaceAll(file.Content, "\n", ""))
if err != nil {
return nil, fmt.Errorf("versions: %s's %s: %w", repo, versions.File, err)
}
v, err := versions.Parse(raw)
if err != nil {
return nil, fmt.Errorf("%s's %w", repo, err)
}
return v, nil
}

func getJSON(ctx context.Context, url string, into any) error {
// Decoded whole once it has all arrived, so an attempt cut short leaves nothing in into.
var raw json.RawMessage
Expand Down
78 changes: 78 additions & 0 deletions versions/upstream/upstream_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package upstream
import (
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"errors"
"io"
Expand Down Expand Up @@ -469,6 +470,9 @@ func TestAnEntryWithAnotherIsBumpedToItsVersion(t *testing.T) {
e, _, err := Bump(t.Context(), v, "utils", "")
require.NoError(t, err)
assert.Equal(t, [2]string{"1.0", sumOf("utils 1")}, [2]string{e.Version, e.Pin})
e, _, err = Bump(t.Context(), v, "utils", "1.0")
require.NoError(t, err, "named at the version it is with")
assert.Equal(t, sumOf("utils 1"), e.Pin)
_, _, err = Bump(t.Context(), v, "utils", "2.0")
assert.ErrorContains(t, err, `utils is with lead, at "1.0": bump lead`)
}
Expand All @@ -489,3 +493,77 @@ func TestAnEntryWithAnArchiveStopsItsLeadersBump(t *testing.T) {
_, _, err = Bump(t.Context(), v, "lead", "v2.0")
assert.ErrorContains(t, err, "src's archive is what a build's git writes")
}

// contents is what GitHub's contents API answers for a file: its bytes in base64, wrapped as the
// API wraps them.
func contents(file string) string {
b64 := base64.StdEncoding.EncodeToString([]byte(file))
return `{"encoding":"base64","content":"` + b64[:10] + `\n` + b64[10:] + `"}`
}

const spinFile = `- name: grafana
kind: download
source: https://example.test/grafana-{version}.tgz
version: 13.4.0
pin: ` + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + `
track: github-release https://github.com/grafana/grafana
- name: day
kind: date
version: 20260101T000000Z
track: today
`

const withSpin = `- name: grafana
kind: download
source: https://example.test/g-{version}
version: v13.3.0
pin: ` + "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + `
track: with spin-stack/spin grafana
`

// An entry with another repository's is at what that repository's versions.yaml says now, read
// through GitHub's API: check says it is behind, a bump takes it, and another version is refused.
func TestAnEntryWithAnotherRepositorysMovesWithIt(t *testing.T) {
serve(t, map[string]string{
"https://api.github.com/repos/spin-stack/spin/contents/versions.yaml": contents(spinFile),
"https://example.test/g-v13.4.0": "grafana 13.4",
})
v, err := versions.Parse([]byte(withSpin))
require.NoError(t, err)
st := Check(t.Context(), v)
require.Len(t, st, 1)
assert.Equal(t, "v13.4.0", st[0].Newest)
assert.True(t, st[0].Behind, st[0].Note)

e, _, err := Bump(t.Context(), v, "grafana", "")
require.NoError(t, err)
assert.Equal(t, [2]string{"v13.4.0", sumOf("grafana 13.4")}, [2]string{e.Version, e.Pin})
_, _, err = Bump(t.Context(), v, "grafana", "v13.5.0")
assert.ErrorContains(t, err, `grafana is with spin-stack/spin's grafana, at "v13.4.0": it moves when that one does`)
}

// Another repository's file that cannot be read, or read as one, or that lacks what the entry
// takes of it, is an error that says which: never a version.
func TestAnotherRepositorysFileIsReadOrRefused(t *testing.T) {
api := "https://api.github.com/repos/spin-stack/spin/contents/versions.yaml"
for _, tc := range []struct{ name, answer, track, want string }{
{"not there, or private with no token", "", "with spin-stack/spin grafana", "GITHUB_TOKEN or GH_TOKEN"},
{"not base64", `{"encoding":"none","content":""}`, "with spin-stack/spin grafana", `came as "none", not base64`},
{"not base64 at all", `{"encoding":"base64","content":"%%%"}`, "with spin-stack/spin grafana", "spin-stack/spin's versions.yaml: illegal base64"},
{"no versions.yaml", contents("- name: x\n"), "with spin-stack/spin grafana", "spin-stack/spin's versions:"},
{"no such entry", contents(spinFile), "with spin-stack/spin qemu", "there is no qemu"},
{"the pin of one that has none", contents(spinFile), "with spin-stack/spin day pin", "grafana is with day's pin, and day has none"},
} {
t.Run(tc.name, func(t *testing.T) {
files := map[string]string{}
if tc.answer != "" {
files[api] = tc.answer
}
serve(t, files)
v, err := versions.Parse([]byte(strings.Replace(withSpin, "with spin-stack/spin grafana", tc.track, 1)))
require.NoError(t, err)
_, err = newest(t.Context(), v, v.Entries[0])
assert.ErrorContains(t, err, tc.want)
})
}
}
97 changes: 66 additions & 31 deletions versions/versions.go
Original file line number Diff line number Diff line change
Expand Up @@ -229,59 +229,94 @@ func Parse(raw []byte) (*Versions, error) {
return v, nil
}

// With is the entry e is moved with, and whether e's version is that entry's pin rather than its
// version: track `with <name>`, or `with <name> pin`. ok is false for any other track.
func (e Entry) With() (name string, pin, ok bool) {
// Along is what an entry tracked with another is moved with: the entry Name, in this file or, when
// Repo is set, in the versions.yaml of that GitHub repository (owner/repo); and whether it takes
// that entry's pin rather than its version.
type Along struct {
Repo, Name string
Pin bool
}

// repository is a GitHub repository as a with track names one: owner/repo.
var repository = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9._-]+$`)

// With is what e is moved with: track `with [owner/repo] <name> [pin]`. ok is false for any other
// track, and err says a with track that is none of those forms.
func (e Entry) With() (a Along, ok bool, err error) {
kind, arg, _ := strings.Cut(e.Track, " ")
if kind != "with" {
return "", false, false
return Along{}, false, nil
}
name, form, _ := strings.Cut(arg, " ")
return name, form == "pin", true
form := strings.Fields(arg)
if len(form) > 0 && strings.Contains(form[0], "/") {
if !repository.MatchString(form[0]) {
return Along{}, true, fmt.Errorf("versions: %s: %q is not a GitHub repository, owner/repo", e.Name, form[0])
}
a.Repo, form = form[0], form[1:]
}
if len(form) == 0 || len(form) > 2 || (len(form) == 2 && form[1] != "pin") {
return Along{}, true, fmt.Errorf("versions: %s: the track %q is not with [owner/repo] <name> [pin]", e.Name, e.Track)
}
a.Name, a.Pin = form[0], len(form) == 2
return a, true, nil
}

// validateWith is an entry tracked with another whose version the file can say: the other is in
// it, is not the entry itself, and is moved by a track of its own, since a chain is one a bump
// would have to walk and a cycle one it never ends. Whether the two agree is not asked here: a
// file in which they do not is one a bump has to be able to read, to move them.
// would have to walk and a cycle one it never ends. One in another repository's file is read only
// by check and bump, which reach it. Whether the two agree is not asked here: a file in which they
// do not is one a bump has to be able to read, to move them.
func (v *Versions) validateWith(e Entry) error {
name, pin, ok := e.With()
if !ok {
return nil
a, ok, err := e.With()
if !ok || err != nil || a.Repo != "" {
return err
}
_, arg, _ := strings.Cut(e.Track, " ")
if form := strings.Fields(arg); len(form) == 0 || len(form) > 2 || (len(form) == 2 && form[1] != "pin") {
return fmt.Errorf("versions: %s: the track %q is not with <name> or with <name> pin", e.Name, e.Track)
}
if name == e.Name {
if a.Name == e.Name {
return fmt.Errorf("versions: %s is with itself", e.Name)
}
leader, err := v.Get(name)
leader, err := v.Get(a.Name)
if err != nil {
return fmt.Errorf("versions: %s is with %s: %w", e.Name, name, err)
return fmt.Errorf("versions: %s is with %s: %w", e.Name, a.Name, err)
}
if _, _, chained := leader.With(); chained {
return fmt.Errorf("versions: %s is with %s, which is with another: name that one", e.Name, name)
if _, chained, _ := leader.With(); chained {
return fmt.Errorf("versions: %s is with %s, which is with another: name that one", e.Name, a.Name)
}
if pin && leader.Pin == "" {
return fmt.Errorf("versions: %s is with %s's pin, and %s has none", e.Name, name, name)
if a.Pin && leader.Pin == "" {
return fmt.Errorf("versions: %s is with %s's pin, and %s has none", e.Name, a.Name, a.Name)
}
return nil
}

// Expected is the version an entry tracked with another is at: the other's pin, or its version
// spelled as e spells its own, with a leading v when e's has one. Upstream writes v3.54.0 in a
// tag and 3.54.0 in a file name, and two entries of the same release say it each their own way.
// Expected is the version an entry tracked with another in this file is at: see ExpectedIn.
func (v *Versions) Expected(e Entry) (string, error) {
name, pin, ok := e.With()
if !ok {
a, ok, err := e.With()
switch {
case err != nil:
return "", err
case !ok:
return "", fmt.Errorf("versions: %s is not tracked with another entry", e.Name)
case a.Repo != "":
return "", fmt.Errorf("versions: %s is with %s's %s, which this file does not have", e.Name, a.Repo, a.Name)
}
leader, err := v.Get(name)
return ExpectedIn(e, v)
}

// ExpectedIn is the version e is at when the file it is with is file: the other's pin, or its
// version spelled as e spells its own, with a leading v when e's has one. Upstream writes v3.54.0
// in a tag and 3.54.0 in a file name, and two entries of the same release say it each their own way.
func ExpectedIn(e Entry, file *Versions) (string, error) {
a, ok, err := e.With()
if err != nil || !ok {
return "", cmp.Or(err, fmt.Errorf("versions: %s is not tracked with another entry", e.Name))
}
leader, err := file.Get(a.Name)
if err != nil {
return "", err
}
if pin {
if a.Pin {
if leader.Pin == "" {
return "", fmt.Errorf("versions: %s is with %s's pin, and %s has none", e.Name, a.Name, a.Name)
}
return leader.Pin, nil
}
version := strings.TrimPrefix(leader.Version, "v")
Expand All @@ -291,11 +326,11 @@ func (v *Versions) Expected(e Entry) (string, error) {
return version, nil
}

// Followers are the entries tracked with name, in the file's order.
// Followers are the entries tracked with name in this file, in the file's order.
func (v *Versions) Followers(name string) []Entry {
var out []Entry
for _, e := range v.Entries {
if leader, _, ok := e.With(); ok && leader == name {
if a, ok, _ := e.With(); ok && a.Repo == "" && a.Name == name {
out = append(out, e)
}
}
Expand Down
Loading
Loading