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.
100 lines
3.3 KiB
Markdown
100 lines
3.3 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
|
|
- [ ] **ADR added** if the change alters an architectural boundary, contract, or trade-off (see [`docs/adr/`](docs/adr/))
|
|
- [ ] English only; no identifying references
|
|
- [ ] Conventional commit message
|
|
|
|
## Decisions
|
|
|
|
Architectural decisions are recorded chronologically as ADRs in
|
|
[`docs/adr/`](docs/adr/). Read [`docs/adr/README.md`](docs/adr/README.md) before
|
|
changing a boundary or contract; add a new ADR (from
|
|
[`docs/adr/TEMPLATE.md`](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`](docs/09-open-questions.md).
|
|
Architecture boundaries are documented in [`docs/06-environments.md`](docs/06-environments.md#iac-boundaries).
|