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.
84 lines
2.9 KiB
Markdown
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?
|