phoebus_os/docs/CONTRIBUTING.md
Phoebus fc64793aec docs: update references after retiring the Bash installer
Point AGENTS.md, README.md and the docs at the Rust-only toolchain and the
moved VM-BOOT-VERIFICATION.md, and drop the Bash installer from DEVELOPMENT.md.
2026-09-20 04:00:19 -07:00

3.1 KiB

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 (developer tooling only)

scripts/, .githooks/ and the Makefile are Bash host tooling, not the product:

  • 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-rs/crates/*/src; unit tests live next to the code).
  • Prefer a fake ProcessRunner + TempDir over root or real disks.
  • Destructive/integration testing only in a disposable qcow2 VM (installer/tests/vm/).
  • The Rust suite must pass before a commit.

Commit messages

Conventional Commits, imperative mood:

<type>(<scope>): <summary>

<body: what changed and why, and how it was verified>

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?