phoebus_os/docs/CONTRIBUTING.md
Phoebus 20bfd82079 docs: add objectives, roadmap, status, architecture and agent guide
Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md.

STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
2026-09-20 02:07:44 -07:00

2.9 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 (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:

<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?