Files

T

eSlider ad7e0a5cbe docs: WireGuard vs SSH, Flux GitOps, CONTRIBUTING with TDD-first

Document why WireGuard and SSH are complementary layers, add Flux
boundaries for the ground segment, shared var/ data paths in docs/06,
and a contributor guide with the required test-first workflow.

2026-07-08 20:17:34 +01:00

2.9 KiB

Raw Blame History

Contributing

Thank you for helping improve Swarm House. This repository is a self-contained design proposal for an on-prem data platform for autonomous drone swarms — all contributions must follow the rules in AGENTS.md.

TDD first (required)

Every change to executable code ships with tests before or alongside the implementation — never as an afterthought.

Red: write or extend a failing test that captures the behaviour you need.
Green: implement the smallest change that makes it pass.
Refactor: clean up without weakening the test.

The CI pipeline enforces this:

Gate	When it runs
`pytest tests/`	Every push/PR (`verify` job)
`RUN pytest tests/` in the simulator Docker build	Every `docker build` — a red test blocks the image
Smoke flight + DuckDB assertion	Every push/PR
Trivy scan	After verify passes

Test locations:

simulator/tests/ — Python unit tests (SQL gate, broadcast codec, writer layout, flight kinematics)
Prototype: npm run build / tsc --noEmit before UI changes

Local development

Fast inner loop (Compose)

cd simulator
pip install -r requirements.txt
pytest tests/ -q                          # run tests first
DRONE_COUNT=5 docker compose up --build   # writes to ../var/t1

Full ground miniature (k3d + Terraform + Flux)

ansible-playbook infra/ansible/sim-cluster.yml
cd infra/terraform/sim-env && terraform init && terraform apply
cd ../ground && terraform init && terraform apply
cd ../../prototype && npm install && npm run dev   # press "go live"

Shared data directories (gitignored, created automatically):

Path	Tier	Contents
`var/t1/`	T1 live lake	In-flight Parquet from Compose or k3d fleet
`var/t3/`	T3 warehouse	Offloaded historical partitions

Override with SWARM_T1_DIR / SWARM_WAREHOUSE_DATA / SWARM_SIM_DATA env vars.

Prototype only

cd prototype && npm install && npm run dev

Commit messages

Conventional Commits only:

feat: add warehouse offload cron schedule variable
fix: reject COPY statements in the SQL gate
docs: clarify WireGuard vs SSH layering
test: cover broadcast frame roundtrip

Never include AI tool references, Co-authored-by trailers for assistants, or identifying names of people, companies, or locations.

Pull request checklist

Tests added or updated; pytest tests/ -q passes locally
docker build in simulator/ succeeds (test stage included)
Documentation updated if behaviour or boundaries changed
English only; no identifying references
Conventional commit message

Questions

Open design questions live in docs/09-open-questions.md. Architecture boundaries are documented in docs/06-environments.md.

2.9 KiB Raw Blame History