Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
102 lines (71 loc) · 3.49 KB

DEVELOPMENT.md

File metadata and controls

102 lines (71 loc) · 3.49 KB

Kernel CLI

A command-line tool for deploying and invoking Kernel applications.

Installation

brew install onkernel/tap/kernel

Development Prerequisites

Install the following tools:

Compile the CLI:

make build   # compiles the binary to ./bin/kernel

Run the CLI:

./bin/kernel --help

Development workflow

Useful make targets:

  • make build – compile the project to ./bin/kernel
  • make test – execute unit tests
  • make lint – run the linter (requires golangci-lint)
  • make changelog – generate/update the CHANGELOG.md file using chglog
  • make release – create a release using goreleaser (builds archives, homebrew formula, etc. See below)

Developing Against API Changes

A typical workflow we encounter is updating the API and integrating those changes into our CLI. The high level workflow is (update API) -> (update SDK) -> (update CLI). Detailed instructions below

  1. Get added to https://www.stainless.com/ organization
  2. For the given SDK version switch to branch changes - see https://app.stainless.com/docs/guides/branches
  3. Update openapi.stainless.yml with new endpoint paths, objects, etc
    1. Note: https://github.com/stainless-sdks/kernel-config/blob/main/openapi.stainless.yml is the source of truth. You can pull older versions as necessary
  4. Update openapi.yml with your changes
  5. Iterate in the diagnostics view until all errors are fixed
  6. Hit Save & build branch
  7. This will then create a branch in https://github.com/stainless-sdks/kernel-go
  8. Using either your branch name or a specific commit hash you want to point to, run this script to modify the CLI's go.mod:
./scripts/go-mod-replace-kernel.sh <commit | branch name>

Releasing a new version

Releases are automated via GitHub Actions. Simply push a version tag and the release workflow will handle the rest.

To release:

# Find the latest version
git describe --abbrev=0

# Create and push a new tag (bump version following https://semver.org/)
git tag -a v<VERSION> -m "Version <VERSION>"
git push origin v<VERSION>

The release workflow will automatically:

  • Build binaries for darwin, linux, and windows (amd64 and arm64)
  • Create a GitHub release with changelog
  • Publish to npm as @onkernel/cli
  • Update the Homebrew formula in onkernel/homebrew-tap

Required GitHub Secrets

The following secrets must be configured in the repository settings:

Secret Description
GH_PAT GitHub Personal Access Token with repo scope. Must have write access to both this repository (for creating releases) and onkernel/homebrew-tap (for updating the Homebrew formula). Create at https://github.com/settings/tokens/new?scopes=repo
GORELEASER_KEY GoReleaser Pro license key (required for npm and homebrew publishing)
NPM_TOKEN npm access token for publishing @onkernel/cli

Local dry-run (optional)

To test the release process locally before pushing a tag:

Prerequisites:

  • Install goreleaser-pro via brew install --cask goreleaser/tap/goreleaser-pro
  • Export GORELEASER_KEY=<license key from 1pw>
make release-dry-run

This will check that everything is working without actually releasing anything.