Thales Maciel
8ba920eda6
Keep the user-facing docs aligned with the current Go control plane instead of the older one-VM-at-a-time and ambiguous rootfs rebuild flows. Document concurrent multi-VM lifecycle and set commands, clarify that rebuilt images now include mise plus opencode, and spell out when make rootfs needs an explicit base image. Also update the repo guidelines so future changes keep those behaviors documented.
42 lines
3.1 KiB
Markdown
42 lines
3.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `cmd/banger` and `cmd/bangerd` are the primary user-facing entrypoints.
|
|
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker, and system integration code.
|
|
- `customize.sh`, `make-rootfs.sh`, and `interactive.sh` remain as manual rootfs/customization helpers; normal VM lifecycle, NAT, `.vm` DNS, and daemon-driven image builds are handled by the Go control plane.
|
|
- Source checkouts use a generated `./runtime/` bundle for Firecracker, kernels, modules, rootfs images, and helper copies. Bundle defaults come from `./runtime/bundle.json` when present. Those runtime artifacts are not meant to be tracked directly in Git.
|
|
- The daemon keeps state under XDG directories rather than the old repo-local `state/` layout.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `make build` builds `./banger` and `./bangerd`.
|
|
- `make runtime-bundle` bootstraps `./runtime/` from the archive referenced by `RUNTIME_MANIFEST`; the checked-in `runtime-bundle.toml` is only a template.
|
|
- `banger` validates required host tools per command and reports actionable missing-tool errors; do not assume one workstation's package set.
|
|
- `./banger vm create --name testbox` creates and starts a VM.
|
|
- `./banger vm ssh testbox` connects to a running guest.
|
|
- `./banger vm stop testbox` stops a VM while preserving its disks.
|
|
- `./banger vm stop vm-a vm-b vm-c` and `./banger vm set --nat web-1 web-2` are supported; multi-VM lifecycle and `set` actions fan out concurrently through the CLI.
|
|
- `./banger tui` launches the terminal UI.
|
|
- `make test` runs `go test ./...`.
|
|
- `./verify.sh` runs the smoke test for the Go VM workflow.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Go code should stay small, direct, and standard-library-first unless there is a clear reason otherwise.
|
|
- Shell helpers use Bash with `set -euo pipefail`; keep remaining shell scripts strict and explicit.
|
|
- Prefer lowercase filenames with short descriptive names.
|
|
- Use `gofmt` for Go formatting; no extra formatter is configured for shell files.
|
|
|
|
## Testing Guidelines
|
|
- Primary automated coverage is `go test ./...`.
|
|
- Manual verification for VM lifecycle changes: `./banger vm create`, confirm SSH access, then stop/delete the VM.
|
|
- Rebuilt images now include `mise` plus `opencode` by default; if you change guest provisioning, document whether users need to rebuild `./runtime/rootfs-docker.ext4` or another base image to pick it up.
|
|
- If you add a new operational workflow, document how to exercise it in `README.md`.
|
|
- For NAT changes, verify both guest outbound access and host rule cleanup, for example with `./verify.sh --nat`.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Git history uses short, imperative subjects.
|
|
- Prefer a real commit body when the change affects lifecycle behavior, storage semantics, or host integration.
|
|
- PRs should call out runtime requirements, migration impact, and any host-side verification performed.
|
|
|
|
## Security & Configuration Tips
|
|
- The VM workflow requires `sudo` and `/dev/kvm` access; do not commit secrets.
|
|
- `id_ed25519` lives inside the runtime bundle; rotate or replace it before publishing a shared bundle.
|