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

84 lines
2.9 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 (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?