Contributing

Contributions are welcome. This page covers how to build, test and submit a change.

Development Setup

You need Go 1.26 or later.

git clone https://github.com/<your-user>/capsailer-cli.git   # your fork
cd capsailer-cli
go mod download
go build -o capsailer ./cmd/capsailer

make build does the same and writes bin/capsailer with the version set.

Project Layout

Path	Purpose
`cmd/capsailer/`	The CLI: command definitions and flags
`pkg/build/`	`build`: downloads images and charts, creates the bundle
`pkg/dockerarchive/`	Reads `docker save` archives and pushes images; the naming rule shared with chart rewriting
`pkg/helm/`	Rewrites image references in chart `values.yaml`
`pkg/registry/`	Kubernetes manifests for the built-in registry and ChartMuseum
`pkg/utils/`	Manifest loading, safe bundle extraction, progress bars
`docs/`	This documentation
`examples/`	Sample manifest and values file

Tests

go test ./...            # all tests
go test -race ./...      # with the race detector

Tests start an in-memory registry, so they need no network or cluster.

To try a change by hand against a real registry without Docker, build the test registry from go-containerregistry and run it:

go build -o /tmp/registry github.com/google/go-containerregistry/cmd/registry
/tmp/registry &                       # listens on localhost:1338
./capsailer push --bundle bundle.tar.gz --external-registry localhost:1338

Code Style

Before you open a pull request, run:

gofmt -l .                                              # must print nothing
go vet ./...
go run honnef.co/go/tools/cmd/staticcheck@latest ./...
go run golang.org/x/vuln/cmd/govulncheck@latest ./...

CI runs the same checks and fails on unformatted code.

Write comments for exported functions and types.
Follow the Go Code Review Comments.
Add tests for new behavior.

Documentation

If you change a flag, an error message or a behavior, update the docs in the same pull request. Check the command's page under docs/commands/ and the README. To preview:

pip install -r requirements.txt
mkdocs serve

Add a line to CHANGELOG.md for changes users will notice.

Pull Requests

Make sure tests and checks pass.
Update documentation.
Describe the change and why you made it.
Reference related issues.

Releases

A release is created by pushing a tag that starts with v, for example v0.4.0. CI builds the binaries for Linux, macOS and Windows, sets the version from the tag, and publishes a GitHub release.

Issues

Please include:

What you did, with the command and its output
What you expected
What happened instead
capsailer --version and your OS

License

By contributing, you agree that your contributions are licensed under the project's Apache License 2.0.