/contributing

Reports and pull requests are welcome.

This is a personal project, so replies can take a few days. Every issue gets read.

01Where to report

Pick the repository by when it went wrong.

Problem	Where	Include
The install failed, or the new install won't boot	ephemeral-nixos	The end of `/tmp/ephemeral-install.log`; `/tmp/ephemeral-install-ui.log` if the screens went wrong
Anything after the machine boots	ephemeral-nixos-config	The output of `ephemeral-report`, read through first
A hardware report, working or not	ephemeral-nixos	The output of `lspci -nn`

02Pull requests

Before you open one.

01
Open an issue first for anything bigger than a fix, so the approach is agreed before you spend the time.
02
Read ARCHITECTURE.md in the repository you're changing. A change that breaks one of its rules needs a reason in the pull request.
03
Send it to the right repository. The installer repo only holds the installer, the ISO and the install test; changes to the installed system go to the config.
04
One feature per file under modules/, adding to the shared modules, with no imports between files.
05
Add a line to CHANGELOG.md under the next version. Anything that breaks existing machines goes first, under Breaking, with what to do about it.
06
Update the docs page that describes what you changed, in the same pull request.
07
No machine files or secrets. The hooks and CI refuse settings.json, hardware-configuration.nix, keys and tokens.

By contributing you agree that your work is released under the MIT License.

03Checks

Run what CI runs.

In the config, turn on the git hooks once per clone. CI runs the secret scan, actionlint and zizmor, shellcheck, nixfmt, nix flake check, feature and settings checks, and script tests against fake commands; the VM boot tests run once the maintainer adds the boot-test label.

A change that should only move code must leave every machine's system unchanged; drv-diff.sh shows it. Every fixed bug gets a test that fails without the fix.

In the installer, keep shellcheck clean, validate every new answer in scripts/common.sh, and for changes to the scripts run the install test, with gh workflow run install-test.yml --ref <branch> or locally.

Details: Working on the config · Working on the installer

config: hooks

git config core.hooksPath .githooks

config: checks and a boot test

cp settings.example.json settings.json
cp hardware-configuration.example.nix hardware-configuration.nix
nix flake check
nix build path:.#checks.x86_64-linux.boot -L

config: a change that only moves code

.github/drv-diff.sh save /tmp/before.json
# make the change
.github/drv-diff.sh compare /tmp/before.json

installer: the install test

printf '{"username": "alice"}\n' > settings.json
cp hardware-configuration.example.nix hardware-configuration.nix
nix build path:.#checks.x86_64-linux.install -L

04This website

Corrections to the site.

Every docs page links to the repository file it's adapted from; fix the text there first. For the site itself, open an issue in the config repository.