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

4. Run Tests

go test ./...                                       # all tests
go test ./pkg/svc/provisioner/cluster/kind          # specific package
go test -cover ./...                                # with coverage
go test -bench=. -benchmem ./pkg/client/helm        # benchmarks

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 cluster 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, benchmark regression). 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.

Getting Help

Discussions · Issues · Documentation · CONTRIBUTING.md