Contributing¶
Requirements¶
- Go (version pinned in
go.mod) justkind,kubectl, Docker or Podman — for actually running a labuv— for building/serving these docs (nothing else Python-related needed;uv runhandles the rest)
Justfile recipes¶
| Recipe | What it does |
|---|---|
just build |
go build -o astrona ./cmd/astrona |
just install |
Build, then move the binary onto PATH (~/.local/bin by default, override with ASTRONA_INSTALL_DIR) |
just clean |
Remove the built binary |
just fmt |
Fail if any file needs gofmt |
just fmt-fix |
Auto-fix formatting |
just vet |
go vet ./... |
just test |
go test ./... |
just check |
fmt + vet + test — run before committing |
just docs-gen-cli |
Regenerate docs/reference/cli/ from the actual astrona command tree |
just docs |
Serve the docs site locally at http://127.0.0.1:8000 with live reload |
just build-docs |
Build the static docs site (mkdocs build --strict) — what CI runs |
Run just with no arguments to list every recipe.
Working on the docs¶
This site is MkDocs + Material for MkDocs, versioned with mike. Source lives under docs/, config at the repo root mkdocs.yml.
opens a live-reloading local copy. The CLI reference under docs/reference/cli/ is generated (via astrona docgen, a hidden command wired into just docs/just build-docs) — don't hand-edit it, edit the command's Short/Long/flag descriptions in cmd/astrona/cmd_*.go instead.
Versioning and deployment (on push to main and on release tags) are handled by .github/workflows/docs.yml — see that file for the exact mike deploy invocations.
Security-sensitive areas¶
If your change touches remote script execution, QEMU base image handling, remote config fetching, git config sources, or path resolution, read the "Security-sensitive areas" section of CLAUDE.md first — these are explicit trust boundaries with existing conventions (HTTPS-only, size caps, path containment) that new code should follow.