Contributing#

Toolchain#

Go 1.25 · Docker · protoc (+ protoc-gen-go, protoc-gen-go-grpc, protoc-gen-grpc-gateway) · dot (Graphviz) · rsvg-convert · hugo (extended, for these docs) · just.

Local setup#

# 1. start CockroachDB (single-node, insecure) for dev
just up                 # docker compose up

# 2. apply migrations and generate a fleet
rackattack migrate
rackattack fleet new --preset example

# 3. run the service (gRPC :8080, REST :8081)
rackattack serve

# 4. ask a blast-radius question over REST
curl -s localhost:8081/rackattack.v1.Rackattack/PowerBlastRadius \
  -d '{"source_ref":"feed:B-3"}'

Common just recipes: up / down (CockroachDB), bench (hyperfine on hot queries), image (container build), k3d-up / k3d-down (local cluster), and the docs recipes below.

Building these docs#

just docs-diagrams   # compile site/diagrams/*.dot → site/static/diagrams/*.svg
just docs-serve      # compile diagrams, then `hugo server` with live reload
just docs-build      # compile diagrams, then `hugo --minify` into site/public

Diagrams are authored as Graphviz .dot in site/diagrams/ (committed) and compiled to SVG (gitignored build artifacts) — the same diagram engine the product uses for its renders. To add or change a diagram, edit the .dot source and re-run just docs-diagrams. The site is deployed to GitHub Pages by a GitHub Actions workflow on push to main.

Sending a change#

The per-PR feature-branch loop and the stack/process conventions are documented in CONTRIBUTING.md and WORKFLOW.md. Commits are small, single-purpose, and reference issue numbers.