Development Guide

Prerequisites

Required: Go 1.26.1+ (go version ≥ 1.26.1), Docker (docker ps without errors), Git.

Optional: Node.js 24 (docs), golangci-lint, VSCode with Go extension.

Development Setup

1. Clone the Repository

git clone https://github.com/devantler-tech/ksail.git
cd ksail

2. Install Dependencies

go mod download
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest  # optional
cd docs/ && npm ci && cd ..  # docs only

3. Build KSail

go build -o ksail && ./ksail --version

Native desktop app

Desktop shares the root Go module and uses the desktop build tag. Default CLI builds and tests do not compile the native webview. Maintain both entry points with go mod tidy at the repository root.

make desktop                     # stages the UI and builds the native app
make desktop-app                 # macOS app bundle
go test -tags desktop ./desktop  # native tests

Linux needs GTK4 and WebKitGTK 6.0 development packages; macOS needs Xcode command line tools. The desktop workflow checks native tests and macOS release packaging.

4. Run Tests

go test ./...                                       # all tests
go test ./pkg/svc/provisioner/cluster/kind          # specific package
go test -cover ./...                                # with coverage

5. Run Linters

golangci-lint run        # all linters
golangci-lint run --fix  # auto-fix (import order, etc.)

Project Structure

See CONTRIBUTING.md for the full package structure and descriptions of each package. internal/ packages can only be imported within the ksail module; pkg/ packages are public. Circular dependencies are not allowed.

Development Workflow

Create a feature branch, make focused atomic changes, write tests, and update docs:

go test ./... && golangci-lint run && go build -o ksail
./ksail project init                                       # Smoke test
git add . && git commit -m "feat: add widget to cluster create" && git push origin feature/my-feature

Commit types: feat, fix, docs, refactor, test, chore, perf. Open a PR with a clear description and ensure CI passes.

Coding Standards

For Go style, naming conventions, error handling, testing patterns, and implementation guidelines, see CONTRIBUTING.md § Code Style.

Working on Documentation

cd docs/
npm ci           # install dependencies
npm run dev      # serve at http://localhost:4321
npm run build    # build to docs/dist/
npm run preview  # preview production build

Debugging

Enable Debug Logging

KSail doesn’t have built-in debug logging yet. Use temporary fmt.Printf("DEBUG: value = %+v\n", value) statements or the Delve debugger:

go install github.com/go-delve/delve/cmd/dlv@latest
dlv test -- -test.run TestName    # debug a test
dlv exec ./ksail -- cluster create # debug the binary

VSCode users can set breakpoints and press F5 with a .vscode/launch.json configuration.

Common Issues

Error	Fix
“Docker not available”	Verify Docker is running: `docker ps`. Check Docker Desktop is started (macOS/Windows) or socket permissions (Linux).
“Go version mismatch”	Run `go version` — must be 1.26.1+. Update from go.dev/dl.
“Import cycle not allowed”	Move shared types to `pkg/apis/` or a utility package. Avoid circular imports.
“Linter failures”	Run `golangci-lint run --fix` to auto-fix. Check `.golangci.yml` for enabled linters; some issues require manual fixes.

CI/CD and Releases

CI runs on pull requests and merges to main (build, test, lint). Releases are automated — push to main triggers tagging, which triggers GoReleaser publishing. For workflow details, see the CI section in CONTRIBUTING.md; for the full release process, see Release Process.

The Go CodeQL job checks extraction diagnostics and requires real CLI and desktop function bodies in its database. A failed module extraction fails the job even when CodeQL uploads analysis results successfully. Fix the reported extraction failure and rerun the job; an incomplete database does not establish a clean scan.

Getting Help

Discussions · Issues · Documentation · CONTRIBUTING.md