eSlider
ad7e0a5cbe
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.
91 lines
2.9 KiB
Markdown
91 lines
2.9 KiB
Markdown
# 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).
|