eSlider
d3ccd6f94e
Add docs/adr/ with a chronological ADR set reconstructed from the project history (no orchestrator, one storage format, derived-state sync, SQL-over-SSH contract, WireGuard beneath SSH, IaC boundaries, non-root image, runtime data paths, bounded lake scans), an index README, and a template. Distinguish repo-local ADRs from ecosystem-wide ASRs. Expand AGENTS.md with a decision-records section and a runtime/operations guide (service URLs, rebuild workflow, CPU budget knobs). Reference the ADRs from README, CONTRIBUTING, and the affected design docs, and add an open question for T1 partition pruning.
3.3 KiB
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 --noEmitbefore 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/ -qpasses locally docker buildinsimulator/succeeds (test stage included)- Documentation updated if behaviour or boundaries changed
- ADR added if the change alters an architectural boundary, contract, or trade-off (see
docs/adr/) - English only; no identifying references
- Conventional commit message
Decisions
Architectural decisions are recorded chronologically as ADRs in
docs/adr/. Read docs/adr/README.md before
changing a boundary or contract; add a new ADR (from
docs/adr/TEMPLATE.md) rather than editing an Accepted
one when you reverse course.
Questions
Open design questions live in docs/09-open-questions.md.
Architecture boundaries are documented in docs/06-environments.md.