Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (96 loc) · 5.87 KB

AGENTS.md

File metadata and controls

111 lines (96 loc) · 5.87 KB
Raw

For Humans

This is a compact AGENTS.md file for Cloud Hypervisor. It is meant to help automated coding agents make useful changes that stay safe, reviewable, and compatible with the project's normal engineering constraints.

This checkout is a Cyberus Technology fork of Cloud Hypervisor. It is maintained independently from upstream, while still following upstream contribution and code-quality guidance unless fork-specific requirements say otherwise.

For LLMs

Project Context

  • Start with README.md for the project shape and CONTRIBUTING.md for the contribution rules, coding style, commit message guidance, and LLM assistance disclosure policy. Following CONTRIBUTING.md is crucial!
  • The main supported architectures are x86_64 and aarch64; the main hypervisor backends are KVM and MSHV. x86_64 with KVM gets the most regular exercise, but changes must not make the other first-class targets worse.
  • Treat live migration and the vCPU lifecycle as first-class production areas. Preserve deterministic state transfer, robust failure handling, correct device and memory state, and explicit race-free vCPU state transitions.

Change Guidelines

  • Prefer correctness, safety, and readability over micro-optimizations. Keep changes small, reviewable, and aligned with the existing crate/module boundaries. Avoid speculative changes and unrelated refactoring.
  • For API, config, migration, device model, or hypervisor boundary changes, consider the effect on all architectures and all backends. Changes to one backend can be okay if the other backend still functions properly and could be extended or modified later.
  • Follow Rust best practices and the style already present in the touched code.
  • Avoid new dependencies unless the benefit is clear and local alternatives are not enough.
  • Preserve existing behavior unless the requested change explicitly needs a behavior change; refactors must preserve behavior. Call out compatibility or migration implications.
  • Prefer simple solutions over unnecessary traits, excessive indirection, or premature abstraction.
  • Prefer Result over panics for recoverable production-path errors. Handle syscall and KVM ioctl return values explicitly and include useful context in error messages.
  • Do not invent APIs, behavior, or requirements. If something is uncertain, state the uncertainty and proceed only with minimal, explicit assumptions.

Safety and Domain Notes

  • Prefer safe Rust. If unsafe is necessary, keep it narrow, add a SAFETY: comment with the invariants, and make sure the surrounding code upholds them.
  • Assume concurrency matters. Avoid races, unsynchronized shared state, and implicit ordering assumptions; prefer clear ownership and synchronization.
  • Keep KVM code aligned with the kernel API. Do not rely on undocumented behavior or ignore backend-specific failure modes.
  • Keep docs and comments short and useful. Document non-trivial invariants at struct definitions and critical state transitions.
  • Logging should be minimal and high signal. Use info! for important normal state changes that matter in production; use warn! or error! only for abnormal conditions. Keep debug! for focused diagnostics.

Build and Test Notes

  • Some workspace members require the kvm feature to build or test correctly. When a default build failure looks feature-related, retry the narrow command with --features kvm before widening the diagnosis.
  • Prefer narrow crate/test commands while iterating, then broaden verification when the touched surface justifies it.
  • Formatting currently needs nightly-only rustfmt features; use cargo +nightly fmt --all.
  • Add targeted unit tests for bug fixes and non-trivial logic where practical. Keep test scaffolding minimal and focused.
  • Integration tests live in ./cloud-hypervisor/tests/ and are normally driven by ./scripts/dev_cli.sh / ./scripts/run_integration_tests_*.sh. They need host privileges, workloads, and container setup. To build the integration-test code directly without the infrastructure from ./scripts, set the Rust cfg devcli_testenv or simply build through clippy which automatically includes these code paths; otherwise the integration-test code is not included. Do not assume the tests can be run directly in a restricted agent environment; ask the developer to run them when real integration coverage is needed.
  • For broader VM behavior, this fork also uses an external libvirt-tests suite outside this repository. If a change likely needs that coverage, say so and ask whether it should be run, skipped, or handled manually by the developer. Only run it yourself if the developer provides the necessary instructions and access details.

Commit and Patch Formatting

  • Follow the rules in CONTRIBUTING.md, including reviewable commit structure, valid component prefixes, 72-column commit messages, and a Signed-off-by trailer.
  • Lines in a commit message that are allowed to exceed the 72-column limit are specified in ./scripts/gitlint/rules.
  • For LLM-assisted changes, follow the disclosure guidance in CONTRIBUTING.md: use the project's Assisted-by: trailer when disclosure is needed, and do not add Co-authored-by or similar trailers unless that policy changes.
  • Temporary allowances such as #[allow(unused)] or ignored tests are only acceptable if resolved within the same commit series or paired with a clear TODO referencing a ticket. Ask the developer if in doubt.
  • Commits need a On-behalf-of: SAP $firstname.$lastname@sap.com trailer: e.g.: 
    $component: $summary

$body

On-behalf-of: SAP philipp.schuster@sap.com
Signed-off-by: Philipp Schuster <philipp.schuster@cyberus-technology.de>
    as our work is sponsored by SAP, which gets its money from the EU (Apeiro project). The enforcing CI rule is in ./scripts/gitlint/rules/on-behalf-of-marker.py