| 1 |
# Contributing |
| 2 |
|
| 3 |
Solo project. External contributions aren't accepted yet, the design is still |
| 4 |
moving. When that changes this file will grow. |
| 5 |
|
| 6 |
## Working in this repo |
| 7 |
|
| 8 |
- Design and load-bearing decisions live in `~/Wiki/quasi-overview.md`, not here. |
| 9 |
- Work backlog is in GoingsOn (project `quasicoherent`), not `todo.md`. |
| 10 |
- Rust 2024 edition, latest stable toolchain. |
| 11 |
- `cargo deny check` must pass before commit. No GPL/LGPL/AGPL, ever. |
| 12 |
- `cargo fmt` + `cargo clippy --all-targets` clean. |
| 13 |
- Commits are concise, imperative, no emoji. |
| 14 |
|
| 15 |
## Measuring the shape-function population |
| 16 |
|
| 17 |
`scripts/population.py` answers how many functions across MNW, goingson and |
| 18 |
audiofiles return a description type. That number is the denominator of the |
| 19 |
declaration transition, and five different answers to it existed before the |
| 20 |
script, none reproducible, because none had written its predicate down. |
| 21 |
|
| 22 |
``` |
| 23 |
python3 scripts/population.py # the count, per tree |
| 24 |
python3 scripts/population.py --list # path:line name -> type |
| 25 |
python3 scripts/population.py --json # the same, machine-readable |
| 26 |
python3 scripts/population.py --selftest # the predicate against known answers |
| 27 |
``` |
| 28 |
|
| 29 |
Two rules if you use it. **Run `--selftest` first**, because every case in it is |
| 30 |
a mistake this script has actually made. And **re-run it rather than quoting a |
| 31 |
number from a note**: the predicate is stable and the count is not. |
| 32 |
|
| 33 |
The predicate itself, and what it deliberately excludes, is documented in the |
| 34 |
script's header and in `~/Wiki/quasi-declare-form.md` section 2. |
| 35 |
|
| 36 |
## The rule this repo exists to hold |
| 37 |
|
| 38 |
**Nothing in `quasi-router` may import a host crate.** Not `tauri`, not `axum`, |
| 39 |
not `wry`. Those are adapters written on top of the router, and the moment one |
| 40 |
of them appears in its dependency tree the stack has a host again. |
| 41 |
|
| 42 |
The same rule applies one level up: the router returns a description, never |
| 43 |
markup. A route that returns HTML is a webview route wearing a neutral name. |
| 44 |
|
| 45 |
## Admitting a new boundary |
| 46 |
|
| 47 |
quasi owns seams, not vendors. Before adding a crate or a trait that wraps a |
| 48 |
dependency, answer one question: |
| 49 |
|
| 50 |
**Which two implementations does this have, today or already committed to?** |
| 51 |
|
| 52 |
If the answer is one, it is an indirection and it does not belong here yet. |
| 53 |
Boundaries enter when the second implementation exists, not when it is |
| 54 |
imagined. |
| 55 |
|
| 56 |
Two further exclusions, both deliberate: |
| 57 |
|
| 58 |
- Ubiquitous and stable with no plausible alternative (`tokio`, `serde`, |
| 59 |
`tracing`, `chrono`, `uuid`, `thiserror`). Wrapping buys nothing. |
| 60 |
- Dependencies whose value *is* their API surface. `sqlx`'s compile-time-checked |
| 61 |
queries are the reason to use it, so quasi configures the driver and runs the |
| 62 |
migrations and queries stay written against `sqlx`. |
| 63 |
|
| 64 |
## Adding a component crate |
| 65 |
|
| 66 |
Crates are scaffolded when they start, not up front: |
| 67 |
|
| 68 |
``` |
| 69 |
cargo new --lib crates/quasi-wry |
| 70 |
``` |
| 71 |
|
| 72 |
Then add it to `Cargo.toml`'s `[workspace] members`, add the `[lints] workspace |
| 73 |
= true` block, and inherit `edition` / `rust-version` / `authors` / `repository` |
| 74 |
/ `license` from `[workspace.package]`. |
| 75 |
|