# Contributing

Solo project. External contributions aren't accepted yet, the design is still
moving. When that changes this file will grow.

## Working in this repo

- Design and load-bearing decisions live in `~/Wiki/quasi-overview.md`, not here.
- Work backlog is in GoingsOn (project `quasicoherent`), not `todo.md`.
- Rust 2024 edition, latest stable toolchain.
- `cargo deny check` must pass before commit. No GPL/LGPL/AGPL, ever.
- `cargo fmt` + `cargo clippy --all-targets` clean.
- Commits are concise, imperative, no emoji.

## Measuring the shape-function population

`scripts/population.py` answers how many functions across MNW, goingson and
audiofiles return a description type. That number is the denominator of the
declaration transition, and five different answers to it existed before the
script, none reproducible, because none had written its predicate down.

```
python3 scripts/population.py            # the count, per tree
python3 scripts/population.py --list     # path:line name -> type
python3 scripts/population.py --json     # the same, machine-readable
python3 scripts/population.py --selftest # the predicate against known answers
```

Two rules if you use it. **Run `--selftest` first**, because every case in it is
a mistake this script has actually made. And **re-run it rather than quoting a
number from a note**: the predicate is stable and the count is not.

The predicate itself, and what it deliberately excludes, is documented in the
script's header and in `~/Wiki/quasi-declare-form.md` section 2.

## The rule this repo exists to hold

**Nothing in `quasi-router` may import a host crate.** Not `tauri`, not `axum`,
not `wry`. Those are adapters written on top of the router, and the moment one
of them appears in its dependency tree the stack has a host again.

The same rule applies one level up: the router returns a description, never
markup. A route that returns HTML is a webview route wearing a neutral name.

## Admitting a new boundary

quasi owns seams, not vendors. Before adding a crate or a trait that wraps a
dependency, answer one question:

**Which two implementations does this have, today or already committed to?**

If the answer is one, it is an indirection and it does not belong here yet.
Boundaries enter when the second implementation exists, not when it is
imagined.

Two further exclusions, both deliberate:

- Ubiquitous and stable with no plausible alternative (`tokio`, `serde`,
  `tracing`, `chrono`, `uuid`, `thiserror`). Wrapping buys nothing.
- Dependencies whose value *is* their API surface. `sqlx`'s compile-time-checked
  queries are the reason to use it, so quasi configures the driver and runs the
  migrations and queries stay written against `sqlx`.

## Adding a component crate

Crates are scaffolded when they start, not up front:

```
cargo new --lib crates/quasi-wry
```

Then add it to `Cargo.toml`'s `[workspace] members`, add the `[lints] workspace
= true` block, and inherit `edition` / `rust-version` / `authors` / `repository`
/ `license` from `[workspace.package]`.