# Contributing ## Golden rules 1. Read `AGENTS.md` and the reading order in it before changing anything. 2. Prefer upstream tools and Gentoo conventions over new code. 3. Keep the proven boot path working. If a change could regress it, verify in the disposable VM before committing. 4. Never commit secrets, the ISO, build output or session transcripts. 5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior or verification changes. ## Rust standards - No `unsafe`. If it is genuinely required, keep it tiny, document the invariants, and test it. (The TUI uses `std::io::IsTerminal` rather than a foreign `isatty`.) - No `unwrap`/`expect` in privileged paths. Return structured `thiserror` errors that carry stage, operation and exit status. - Never `sh -c`. Every command goes through `phoebus-executor::Exec` with separate arguments; secrets go over stdin. - Every target write goes through `TargetRoot`. - Destructive functions require `&DestructiveAuthorization`. - Keep unit-testable logic pure and in `phoebus-core`; keep privileged effects in `phoebus-executor` behind `ProcessRunner`. ## Bash standards (while it remains) - `shellcheck -S warning` clean. - Never `local a="$1" b="$a"` (the dynamic-scoping bug class). Use two `local` statements. - Never write to a host path without the target root. - Quote all expansions. ## Tests - Add a regression test for every meaningful bug (see the tests in `installer/tests/` and `installer-rs/crates/*/src`). - Prefer a fake `ProcessRunner` + `TempDir` over root or real disks. - Destructive/integration testing only in a disposable qcow2 VM. - Both suites must pass before a commit. ## Commit messages Conventional Commits, imperative mood: ``` (): ``` Types: `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `chore`. Scopes: `installer`, `rust`, `core`, `executor`, `ai`, `tui`, `vm`, `docs`, `git`, `release`. Examples: ``` feat(rust): add typed SystemAction broker for sys fix(executor): make getuto keyring readable by the verify user docs(git): add migration plan and agent workflow ``` ## Definition of done - [ ] The change is implemented, not merely described. - [ ] Tests added or updated; both suites pass. - [ ] `cargo fmt`/`clippy` clean (when the components are installed). - [ ] `docs/CHANGELOG.md` updated; `docs/STATUS.md` updated if verification changed. - [ ] No secrets, ISO, build output or transcripts staged. - [ ] Committed with a conventional message and pushed when a remote exists. ## Review checklist - Does it weaken encryption, signing, boot protection or disk safety? If so, stop. - Does it globally enable `~amd64` or disable signature verification? If so, stop. - Does it give the LLM a shell, root, secrets or home-directory access? If so, stop. - Does it preserve the proven boot path and the fstab/subvolume ordering? - Is the change observable in the log and covered by a test?