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.
2.9 KiB
2.9 KiB
Contributing
Golden rules
- Read
AGENTS.mdand the reading order in it before changing anything. - Prefer upstream tools and Gentoo conventions over new code.
- Keep the proven boot path working. If a change could regress it, verify in the disposable VM before committing.
- Never commit secrets, the ISO, build output or session transcripts.
- Update
docs/CHANGELOG.mdanddocs/STATUS.mdwhen behavior or verification changes.
Rust standards
- No
unsafe. If it is genuinely required, keep it tiny, document the invariants, and test it. (The TUI usesstd::io::IsTerminalrather than a foreignisatty.) - No
unwrap/expectin privileged paths. Return structuredthiserrorerrors that carry stage, operation and exit status. - Never
sh -c. Every command goes throughphoebus-executor::Execwith 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 inphoebus-executorbehindProcessRunner.
Bash standards (while it remains)
shellcheck -S warningclean.- Never
local a="$1" b="$a"(the dynamic-scoping bug class). Use twolocalstatements. - 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/andinstaller-rs/crates/*/src). - Prefer a fake
ProcessRunner+TempDirover 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/clippyclean (when the components are installed).docs/CHANGELOG.mdupdated;docs/STATUS.mdupdated 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
~amd64or 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?