vhaudiquet
af06264e60
README gains a Library section covering prepare, the exec options (envp, bind targets, arch) and the provisioned-rootfs hot-cell flow. SPEC documents the workspace layout, the library API, the cache sidecars (.digest, .provisioned) and the updated execution flow. AGENTS.md scope paths follow the new crates/ layout.
90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# AGENTS.md
|
|
|
|
Conventions for working in this tree. They apply to every commit; the
|
|
whole history follows them.
|
|
|
|
## Before every commit
|
|
|
|
Run, in order, and make sure they are clean before committing:
|
|
|
|
```sh
|
|
cargo fmt --all
|
|
cargo clippy --all-targets # no new warnings
|
|
cargo test # keep green when touching behavior
|
|
```
|
|
|
|
These mirror CI (`.github/workflows/ci.yml` runs check, `fmt --check`,
|
|
clippy, and `cargo test --all-features`). `cargo fmt` may amend files
|
|
you did not touch — include those changes in the commit (or in a
|
|
separate `chore:` commit) rather than leaving the tree dirty.
|
|
|
|
## Commit messages
|
|
|
|
Follow Conventional Commits with a component scope:
|
|
|
|
```
|
|
<type>(<scope>): <short summary>
|
|
```
|
|
|
|
Rules:
|
|
|
|
- Types: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `build`,
|
|
`ci`, `chore`.
|
|
- Scopes match the component touched — the module name under
|
|
`crates/ecr/src/` (library) or `crates/ecr-cli/src/` (CLI):
|
|
- `cli` — entry point and flags (`crates/ecr-cli/src/main.rs`,
|
|
`crates/ecr-cli/src/cli.rs`)
|
|
- `rootfs` — cache-aware preparation and persistence
|
|
(`crates/ecr/src/rootfs.rs`)
|
|
- `exec` — namespace-mode execution API (`crates/ecr/src/exec.rs`)
|
|
- `config` — config file (`crates/ecr/src/config.rs`)
|
|
- `distro` — distro definitions and mirrors (`crates/ecr/src/distro.rs`)
|
|
- `download` — image download (`crates/ecr/src/download.rs`)
|
|
- `extract` — rootfs extraction (`crates/ecr/src/extract.rs`)
|
|
- `chroot` — chroot setup (`crates/ecr/src/chroot.rs`)
|
|
- `namespace` — Linux namespaces (`crates/ecr/src/namespace.rs`)
|
|
- `mount` — bind mounts and mount table (`crates/ecr/src/mount.rs`)
|
|
- `kernel` — kernel/initramfs handling for `--kernel`
|
|
(`crates/ecr/src/kernel.rs`)
|
|
- `qemu` — QEMU VM mode (`crates/ecr/src/qemu.rs`,
|
|
`crates/ecr/src/qemu_vm.rs`)
|
|
- `utils`, `verbose` — shared helpers (`crates/ecr/src/utils.rs`,
|
|
`crates/ecr/src/verbose.rs`)
|
|
- `deps` — dependency additions/bumps (manifests, lockfile)
|
|
- Omit the scope entirely for repo-wide changes that do not belong to a
|
|
single component (README.md, SPEC.md, root config).
|
|
- Summary: imperative mood ("add", never "added" or "adds"), lowercase
|
|
first letter, no trailing period, max ~72 characters.
|
|
- Body (optional): separated by a blank line, wrapped at 72 columns;
|
|
explain why rather than what. Reference issues as `#123`.
|
|
- A commit touching several components should be split into one commit
|
|
per component when practical; otherwise use the dominant scope.
|
|
- **No merge commits.** Integrate work by rebasing onto the target
|
|
branch (`git rebase`, `git pull --rebase`, `git cherry-pick`); the
|
|
history stays linear. When several work streams run in parallel, land
|
|
them one rebase at a time.
|
|
|
|
### Examples
|
|
|
|
```
|
|
feat(namespace): set unique hostname per run
|
|
fix(extract): handle hard links in rootfs archives
|
|
fix(kernel): parse =PATH syntax for --kernel
|
|
test(chroot): cover path resolution helpers
|
|
feat(qemu): enable KVM when available
|
|
deps: bump nix to 0.31
|
|
docs: document QEMU system mode and =PATH syntax
|
|
chore: apply cargo fmt
|
|
```
|
|
|
|
## Code
|
|
|
|
- Tests live inline as `#[cfg(test)]` modules at the bottom of each
|
|
`src/` module; there is no `tests/` directory. Scope test commits to
|
|
the module under test.
|
|
- Comments state constraints the code cannot show; no narration.
|
|
- Anything user-facing (CLI flags, config keys, error text users act
|
|
on) is reflected in `README.md` before commit.
|
|
- Design decisions that outlive the session go to `SPEC.md`, not to
|
|
new docs or repos.
|