Contributing on Restish

Development Setup

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when changing code, plugins, or docs in the Restish repository.

Build The CLI

go build ./cmd/restish

Build Plugin Binaries

go build ./cmd/restish-bulk
go build ./cmd/restish-csv
go build ./cmd/restish-mcp
go build ./cmd/restish-pkcs11

Run Tests

go test ./...
go test ./internal/cli/...

Run the integration-tag suite before commits that touch CLI or plugin behavior:

go test -tags=integration ./...

Use a temporary GOCACHE when your environment needs an isolated cache:

GOCACHE=/tmp/restish-gocache go test ./...

Update Golden Files

go test -update ./internal/output/...

Build The Docs Site

go run ./cmd/restish-docgen --check
hugo --source site --quiet
scripts/check-doc-links.rb

When command help, global flags, plugin protocol structs, or built-in command plugins change, refresh the checked-in generated regions first:

Design Records

Mon, 01 Jan 0001 00:00:00 +0000

Design records live in docs/design/. They explain why Restish is shaped the way it is: runtime boundaries, config, auth, TLS, OpenAPI command generation, request execution, response normalization, plugins, security, and migration.

When To Read Them

Read design records when you are changing:

persistent config or profile behavior
auth, token storage, external tools, or OAuth flows
TLS, mTLS, or signer plugins
OpenAPI discovery or generated commands
request execution order
pagination, streaming, filtering, or output contracts
plugin protocol or trust boundaries
v1 compatibility and migration behavior

User Docs Trigger

If a design record changes user-visible behavior, update the user docs in the same work. Design records preserve intent; they do not replace guides, recipes, or reference pages.

Docs Maintenance

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when you are changing user-facing behavior and need to make the docs stay honest.

This page is a maintenance workflow, not the source of truth for product behavior. Current behavior comes from the CLI, tests, design records, and live example API. When they disagree, update the docs and capture any remaining follow-up in the project issue tracker or an active design record.

Before You Edit

Check the nearby docs before changing one page in isolation:

Release Packaging

Mon, 01 Jan 0001 00:00:00 +0000

Use this page when preparing a Restish v2 release. It keeps the release artifacts, package-manager metadata, plugin binaries, and docs in the same checklist.

The public install guide assumes the v2 release artifacts are available: Homebrew first for macOS users, then source, mise, GitHub archives, and OCI image options. Before publishing docs, verify each public artifact below rather than adding temporary caveats to the user-facing install path.

Version And Changelog

Update the build version used by release builds.
Update the changelog with user-visible features, breaking changes, migration notes, and plugin protocol changes.
Check the upgrade guide when a v1 behavior changed or a v2 draft command was removed before release.

GitHub Releases

Release archives should include the restish binary for supported macOS, Linux, and Windows targets on amd64 and arm64.