eSlider
b4de3ed076
CI & Release / Verify documentation (push) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify documentation (pull_request) Successful in 5s
CI & Release / Verify simulator (pull_request) Failing after 10s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
Relocate check_docs, check_adrs, and docs_rules; update CI, tests, and docs.
136 lines
5.1 KiB
Markdown
136 lines
5.1 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 |
|
||
| --- | --- |
|
||
| `python bin/check_docs.py` | Every push/PR (`docs-verify` job) — links, glossary anchors, readability rules ([ci-rules](docs/improvement/ci-rules.md)) |
|
||
| `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.
|
||
|
||
## 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](.github/ISSUE_TEMPLATE/default.md) and
|
||
[PR](.github/pull_request_template.md) 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/`](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/`](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).
|