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

88 lines
3.1 KiB
Markdown

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