buoy

A tool to encode the Knative release process logic based on go module versions.

Installation

buoy can be installed and upgraded by running:

go get tableflip.dev/buoy

Usage

Usage:
  buoy [command]

Available Commands:
  check       Determine if this module has release branches or releases available from each dependency for a given release.
  float       Find latest versions of dependencies based on a release.
  help        Help about any command
  needs       Find dependencies based on a base import domain.

Flags:
  -h, --help   help for buoy

Use "buoy [command] --help" for more information about a command.

Check

The check command is used to evaluate if each dependency for the given module
meets the requirements for cutting a release branch. If the requirements are
met based on the ruleset selected, the command will exit with code 0, otherwise
an error message is generated and the with the failed dependencies and exit
code 1. Errors are written to stderr. Verbose output is written to stdout.

Rulesets,
  Release          check requires all dependencies to have tagged releases.
  Branch           check requires all dependencies to have a release branch.
  ReleaseOrBranch  check will use rule (Release || Branch).

Usage:
  buoy check go.mod [flags]

Flags:
  -d, --domain string    domain filter (default "knative.dev")
  -h, --help             help for check
  -r, --release string   release should be '<major>.<minor>' (i.e.: 1.23 or v1.23) [required]
      --ruleset string   The ruleset to evaluate the dependency refs. Rulesets: [Any, ReleaseOrBranch, Release, Branch] (default "ReleaseOrBranch")
  -v, --verbose          Print verbose output.

Example,

$ go run . check $HOME/go/src/knative.dev/eventing-github/go.mod --release 0.18 --verbose
[exit status 0]

$ go run . check $HOME/go/src/knative.dev/eventing-github/go.mod --release 0.19 --verbose
knative.dev/eventing-github not ready for release because of the following dependencies [knative.dev/eventing@master, knative.dev/pkg@master, knative.dev/serving@master, knative.dev/test-infra@master]
[exit status 1]

If you need to see a more verbose output, use --verbose:

$ bouy check $HOME/go/src/knative.dev/eventing-github/go.mod --release 0.18 --verbose
knative.dev/eventing-github
✔ knative.dev/eventing@v0.18.0
✔ knative.dev/pkg@release-0.18
✔ knative.dev/serving@v0.18.0
✔ knative.dev/test-infra@release-0.18
[exit status 0]

$ bouy check $HOME/go/src/knative.dev/eventing-github/go.mod --release 0.19 --verbose
knative.dev/eventing-github
✘ knative.dev/eventing@master
✘ knative.dev/pkg@master
✘ knative.dev/serving@master
✘ knative.dev/test-infra@master
knative.dev/eventing-github not ready for release because of the following dependencies [knative.dev/eventing@master, knative.dev/pkg@master, knative.dev/serving@master, knative.dev/test-infra@master]
[exit status 1]

Float

The goal of the float command is to find the best reference for a given release.
Float will select a ref for found dependencies, in this order (for the Any
ruleset, default):

1. A release tag with matching major and minor; choosing the one with the
   highest patch version, ex: "v0.1.2"
2. If no tags, choose the release branch, ex: "release-0.1"
3. Finally, the default branch, ex: "master"

The selection process for float can be modified by providing a ruleset.

Rulesets,
  Any              tagged releases, release branches, default branch
  Release          tagged releases
  Branch           release branches
  ReleaseOrBranch  tagged releases, release branch

For rulesets that that restrict the selection process, no ref is selected.

Usage:
  buoy float go.mod [flags]

Flags:
  -d, --domain string    domain filter (default "knative.dev")
  -h, --help             help for float
  -r, --release string   release should be '<major>.<minor>' (i.e.: 1.23 or v1.23) [required]
      --ruleset string   The ruleset to evaluate the dependency refs. Rulesets: [Any, ReleaseOrBranch, Release, Branch] (default "Any")
      --strict           strict - only select and return tagged modules (equivalent to Releases ruleset).

Example:

$ buoy float go.mod --release v0.15
knative.dev/eventing@v0.15.4
knative.dev/pkg@release-0.15
knative.dev/serving@v0.15.3
knative.dev/test-infra@release-0.15

Or set domain to and target release of that dependency:

$ buoy float go.mod --release 0.18 --domain k8s.io
k8s.io/api@v0.18.10
k8s.io/apiextensions-apiserver@v0.18.10
k8s.io/apimachinery@v0.18.10
k8s.io/client-go@v0.18.10
k8s.io/code-generator@v0.18.10
k8s.io/gengo@master
k8s.io/klog@master

Note: the following are equivalent releases:

• v0.1
• v0.1.0
• 0.1
• 0.1.0

Needs

Find dependencies based on a base import domain.

Usage:
  buoy needs go.mod [flags]

Flags:
  -d, --domain string   domain filter (default "knative.dev")
      --dot             Produce a .dot file output for use with Graphviz.
  -h, --help            help for needs

Example,

$ buoy needs $HOME/go/src/knative.dev/eventing-github/go.mod
knative.dev/eventing
knative.dev/pkg
knative.dev/serving
knative.dev/test-infra

Or set domain to see a different dependency group:

$ buoy needs $HOME/go/src/knative.dev/eventing-github/go.mod --domain k8s.io
k8s.io/api
k8s.io/apimachinery
k8s.io/client-go

Or as a graph and render using graphvis:

buoy needs $HOME/go/src/knative.dev/eventing/go.mod --dot | dot -Tsvg > /tmp/kn.svg

TODO:

• Support go-import with more than one import on a single page.
• Support release branch templates. For now, hardcoded to Knative style.