swarm-house/CONTRIBUTING.md

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.

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
python bin/check_docs.py	Every push/PR (docs-verify job) — links, glossary anchors, readability rules (ci-rules)
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.

Caveman style (default)

Use caveman-full in issues, pull requests, and reviews unless the author explicitly asks otherwise.

Do	Skip
Short lines, fragments OK	Long preamble ("I wanted to start by saying…")
Lead with what / why / verdict	Filler ("just", "basically", "kind of")
Bullets, checklists	Repeated context already in diff or issue
Exact terms, paths, code	Invented abbreviations or vague "the thing"

Examples

Fluffy	Caveman
I think we should probably consider adding a link checker to CI because links might break.	Add CI link checker. Broken relative links fail merge.
This pull request implements the documentation improvements that were discussed in the audit.	Docs audit: glossary T0–T4, fix ground README link, rsync wording.
LGTM but maybe we could think about whether the anchor format is consistent?	Merge OK. Fix glossary anchors in follow-up (#1).

README intensity: root = caveman-lite; simulator/, prototype/, infra/, docs/adr/ READMEs = caveman-full. Numbered design docs in docs/ stay full prose.

Gitea pre-fills issue and PR templates with this style.

Reviews

Default review voice = caveman-full:

1. Verdict first — merge / wait / no, or approve / request changes
2. Findings — bullet per blocker or nit; file + line when useful
3. Scope — say if issue AC met, partial, or out of scope
4. No essay; link ADR, issue, or doc section instead of restating design

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/) — never edit an existing ADR-*.md; supersede with a new number
• 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.