Files
Willem Vanhulle f9f68b2a68 ci: move CI tasks into Nushell scripts and update dependencies weekly
Replace the shell scripts in flake.nix with Nushell scripts in ci/, exposed
as flake apps in nix/ci-tasks.nix, so every workflow command is a plain nix
call. Build the workspace dependencies in a step of their own, upload to
Cachix only after the builds, and run the formatting check through the
pre-commit hooks.

Automated pushes, tags and pull requests now use the wvhulle-bot account.
A weekly cron updates Cargo.lock and flake.lock and opens or updates one
pull request from bot/dependency-updates.

Claude-Session: https://claude.ai/code/session_01D8dLLgYd8cfR2aQfA5eZXa
2026-11-05 19:59:06 +01:00

137 lines
6.5 KiB
Markdown

# Development
## Layout
| Folder | Holds |
| --- | --- |
| `bootvine/` | the published crate: the library, the `bootvine` binary and the unit and initrd files it installs |
| `scripted-demos/` | the scripted boot, shutdown and passphrase demos, and the VHS tapes that record them |
| `xtask/` | repository tasks run with `cargo xtask` |
| `vm-tests/` | the sample NixOS machines, one folder each with its VM check |
| `nix/` | the crane builds and the NixOS module |
| `recordings/` | ignored output of `record-screencasts`: the scripted demo GIFs and the sample machine WebP recordings, published on the `recordings` branch for the README and the [guide](guide.md) |
`cargo build` and `cargo test` act on every crate. `cargo run` needs the binary:
`--bin bootvine`, `--bin scripted-boot` and so on.
## Setup
Work inside the dev shell (`direnv allow` once, with
[direnv](https://direnv.net)). Version control is
[jj](https://github.com/jj-vcs/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-commit-messages -- origin/main..HEAD
```
Git users can install the same commit-message check and a formatting check as
hooks with `prek install` ([prek](https://github.com/j178/prek), from the dev
shell) or `pre-commit install` ([pre-commit](https://pre-commit.com)). CI runs
the formatting hook with `nix run .#run-pre-commit-hooks`.
## Continuous integration
`.woodpecker/checks.yaml` runs on Codeberg's
[Woodpecker CI](https://woodpecker-ci.org) for every push and pull request: the bootvine build with its tests, the xtask build, clippy,
the pre-commit hooks, an evaluation of every flake output, and the commit-message check on
pull requests. The workspace dependencies are built or fetched in a step of their own. Builds on `main` are pushed to the `wvhulle` [Cachix](https://www.cachix.org) cache, which
`nixConfig` in `flake.nix` offers as a substituter. CI tasks are Nushell scripts in `ci/`, exposed as flake apps in `nix/ci-tasks.nix`. The two VM checks need KVM,
which Codeberg's runners lack, so they only run locally.
## Releases
`.woodpecker/publish-release-and-update-pr.yaml` runs
[release-plz](https://release-plz.dev) after the checks pass on `main`. It
keeps a pull request labelled `release` open on Codeberg that bumps the version
in `Cargo.toml` and adds the new commits to `CHANGELOG.md`. Only `feat`, `fix`
and `perf` commits open one; a `!` or a `BREAKING CHANGE` footer bumps the
minor version while bootvine is below 1.0. Merging that pull request publishes
the crate to crates.io, tags the merge `v<version>` and creates a Codeberg
release with the changelog. Settings are in `release-plz.toml`.
The pipeline needs two Woodpecker secrets: `bot_token`, an access token of the
`wvhulle-bot` Codeberg account, which has write access to the repository, and
`cargo_registry_token`, a crates.io token that may publish new crates and updates. Preview the next release
locally from the dev shell with `release-plz update`.
## Dependency updates
The `weekly-dependency-update` cron runs `.woodpecker/dependency-update-pr.yaml`,
which updates `Cargo.lock` and `flake.lock` and opens or updates one pull request
from the `bot/dependency-updates` branch as `wvhulle-bot`. The checks on that pull
request are the trial build. Commits pushed to the branch by hand stop further
automatic updates until it is merged. Updates that need changes to `Cargo.toml`
stay manual.
## Testing
| What | Command |
| --- | --- |
| Model and render tests | `cargo test --workspace` |
| Scripted demos | `cargo run --bin scripted-boot` (also `scripted-shutdown`, `scripted-luks-unlock`) |
| Sample machines in a window | `nix run .#sample-vm-<machine>`, see the [guide](guide.md#sample-machines) |
| A sample machine's check | `nix build .#checks.x86_64-linux.vm-<machine>` |
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-sample-services.target
cargo run --bin bootvine -- --user --target bootvine-sample-services.target --hold 3s
systemctl --user stop $(ls $units)
systemctl --user disable --runtime $(ls $units)
```
Everything a sample machine needs sits in its own folder under `vm-tests/`:
`machine.nix`, `check.nix` and `check.py`. `vm-tests/shared/` holds the
settings every machine shares, the window setup for `nix run`, the console
helpers for the checks and the screen recorder. A new machine is a new folder
plus its name in `vm-tests/default.nix`.
The VM checks read the console as text, hold the boot at fixed points and wait
on marker files instead of sleeping. The failures check starts each failing
unit by hand, so it knows which one is newest in the panel. While a check runs,
`ScreenRecording` takes a frame every half second through a second QEMU
monitor socket, so it never competes with the driver's own monitor; the frames
land in the check's output under `recording/`. To step through a check by hand, run
`nix run .#checks.x86_64-linux.vm-slow-services.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](https://www.qemu.org) or Chromium.
## Repository tasks
- `nix run .#record-screencasts` re-records the animations from the scripted
demos and turns the frames each VM check captured into
`recordings/<machine>.webp`, for the README and the [guide](guide.md).
- `nix run .#publish-recordings` force-pushes `recordings/` as the single,
parentless commit of the `recordings` branch, which the README and the guide
link to. Keeping the recordings off `main` keeps them out of every clone and
flake fetch.
- `cargo xtask sync-default-config` rewrites the defaults block in
[configuration](configuration.md#defaults) from `bootvine defaults`.
- `cargo run --bin bootvine -- install --destdir <dir> --initrd dracut` stages an install
without touching the system; `cargo run --bin bootvine -- uninstall --destdir <dir>` removes
it again.
## Code style and design
- [Code style](style.md).
- [Architecture](architecture.md): the event loop, the console
takeover and the workarounds for systemd's private socket.