Files
bootvine/CONTRIBUTING.md
T

101 lines
3.7 KiB
Markdown

# Contributing
## Setup
Work inside the dev shell (`direnv allow` once). Version control is jj, not
the `git` CLI.
## Before committing
```sh
cargo clippy --workspace --all-targets
cargo fmt --all
```
Clippy runs with the pedantic lints and forbids absolute paths; formatting
needs the nightly toolchain the dev shell provides.
Commit messages follow [Conventional Commits](https://www.conventionalcommits.org).
jj does not run git hooks, so check the commits you are about to push with:
```sh
nix run .#check-conventional-commits -- origin/main..HEAD
```
Git users can install the same commit-message check and a formatting check as
hooks with `prek install` (from the dev shell) or `pre-commit install`.
## Continuous integration
`.woodpecker/rust-and-flake-checks.yaml` runs on Codeberg for every push and
pull request: the bootvine build with its tests, the xtask build, clippy,
rustfmt, an evaluation of every flake output, and the commit-message check on
pull requests. Builds on `main` are pushed to the `wvhulle` Cachix cache, which
`nixConfig` in `flake.nix` offers as a substituter. The two VM checks need KVM,
which Codeberg's runners lack, so they only run locally.
## Testing
| What | Command |
| --- | --- |
| Model and render tests | `cargo test --workspace` |
| Scripted demos | `cargo run --example boot` (also `shutdown`, `luks`) |
| Sample machine in a window | `nix run .#sample-machine-vm` |
| Boot and shutdown in a VM | `nix build .#checks.x86_64-linux.vm-boot-and-shutdown` |
| Passphrase prompt in a VM | `nix build .#checks.x86_64-linux.vm-luks-passphrase` |
To watch your own user manager start the sample units:
```sh
units=$(nix build --no-link --print-out-paths .#sample-unit-files)
systemctl --user link --runtime $units/*
systemctl --user start --no-block bootvine-demo.target
cargo run -- --user --target bootvine-demo.target --hold 3s
systemctl --user stop $(ls $units)
systemctl --user disable --runtime $(ls $units)
```
The VM checks read the console as text, hold the boot at fixed points and wait
on marker files instead of sleeping. To step through one by hand, run
`nix run .#checks.x86_64-linux.vm-boot-and-shutdown.driverInteractive` and
call `test_script()`.
Prefix VM and recording commands with `env -u LD_LIBRARY_PATH` when your shell
exports libraries that clash with QEMU or Chromium.
## Repository tasks
- `nix run .#record-screencasts` re-records the README animations from the
scripted demos and copies the passphrase screenshot from the VM check.
- `cargo xtask install --destdir <dir> --initrd dracut` stages an install
without touching the system; `cargo xtask uninstall --destdir <dir>` removes
it again.
## Code style
- No comments; names and call flow carry the intent.
- Public fields over getters, durations over raw integers, existing crates over
hand-written formatting.
- Iterator and stream combinators over loops.
## Design notes
### One event loop
Everything runs on one thread. The service manager, the keyboard, the frame
timer, password prompts and termination each produce a stream of inputs; the
streams are merged, applied in batches to a single screen state, and the screen
is drawn once per batch. The live boot and the scripted demos share this loop
and differ only in where their inputs come from.
### systemd's private socket
- zbus rejects it, because PID 1 sends under its well-known name rather than a
unique one. libdbus works.
- libdbus sends its authentication handshake together with the first message,
which systemd leaves unread, so a no-reply ping goes out right after
connecting.
- Surviving the switch to the real root needs a process name starting with `@`,
a unit that is not stopped on isolate, and a chroot through a file descriptor
to the new root taken as soon as the switch is queued.