ecr/AGENTS.md

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:

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 src/:
  • cli — entry point and flags (src/main.rs, src/cli.rs)
  • config — config file (src/config.rs)
  • distro — distro definitions and mirrors (src/distro.rs)
  • download — image download (src/download.rs)
  • extract — rootfs extraction (src/extract.rs)
  • chroot — chroot setup (src/chroot.rs)
  • namespace — Linux namespaces (src/namespace.rs)
  • mount — bind mounts and mount table (src/mount.rs)
  • kernel — kernel/initramfs handling for --kernel (src/kernel.rs)
  • qemu — QEMU VM mode (src/qemu.rs, src/qemu_vm.rs)
  • utils, verbose — shared helpers (src/utils.rs, 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.