Thales Maciel
238bb8a020
Stop treating Firecracker, kernels, modules, and guest images as tracked source files. Source checkouts now resolve runtime assets from ./runtime, while installed binaries keep using ../lib/banger. Add a small runtimebundle helper plus runtime-bundle.toml so make can bootstrap, package, and install a runtime bundle with checksum validation. Update the shell helpers and daemon path hints to fail clearly when the bundle is missing instead of assuming repo-root artifacts. This removes the tracked runtime blobs from HEAD in favor of an ignored local runtime/ tree. Verified with go test ./..., make build, bash -n on the shell helpers, make -n install, and a temporary package/fetch smoke test. The manifest URL/SHA still need a published bundle before fresh clones can bootstrap, and history rewrite remains a separate rollout step.
39 lines
2.4 KiB
Markdown
39 lines
2.4 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 image-build/customization helpers; normal VM lifecycle and NAT management are handled by the Go control plane.
|
|
- Source checkouts use a generated `./runtime/` bundle for Firecracker, kernels, modules, rootfs images, and helper copies. 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 `runtime-bundle.toml`.
|
|
- `./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 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.
|
|
- 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.
|