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
parent cb4664f5ee
commit ad7e0a5cbe
6 changed files with 191 additions and 6 deletions
@@ -0,0 +1,90 @@
+# 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`](AGENTS.md).
+
+## TDD first (required)
+
+Every change to executable code ships with tests **before** or **alongside** the
+implementation — never as an afterthought.
+
+1. **Red:** write or extend a failing test that captures the behaviour you need.
+2. **Green:** implement the smallest change that makes it pass.
+3. **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)
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+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`](docs/09-open-questions.md).
+Architecture boundaries are documented in [`docs/06-environments.md`](docs/06-environments.md#iac-boundaries).