cloud-hypervisor/CONTRIBUTING.md

Contributing to Cloud Hypervisor

Cloud Hypervisor is an open source project licensed under the Apache v2 License and the BSD 3 Clause license. Individual files contain details of their licensing and changes to that file are under the same license unless the contribution changes the license of the file. When importing code from a third party project (e.g. Firecracker or crosvm) please respect the license of those projects.

New code should be under the Apache v2 License.

Coding Style

We follow the Rust Style convention and enforce it through the Continuous Integration (CI) process calling into rustfmt, clippy, and other well-known code quality tool of the ecosystem for each submitted Pull Request (PR).

Basic Checks

# We currently rely on nightly-only formatting features
cargo +nightly fmt --all 
cargo check --all-targets --tests
cargo clippy --all-targets --tests
# Please note that this will not execute integration tests.
cargo test --all-targets --tests

# To lint your last three commits
gitlint --commits "HEAD~3..HEAD"

[Optional] Run Integration Tests

Caution: These tests are taking a long time to complete (40+ mins) and need special setup.

 bash ./scripts/dev_cli.sh tests --integration -- --test-filter '<optionally filter test by name pattern>' 

Setup Commit Hook

Please consider creating the following hook as .git/hooks/pre-commit in order to ensure basic correctness of your code. You can extend this further if you have specific features that you regularly develop against.

#!/bin/sh

cargo +nightly fmt --all -- --check || exit 1
cargo check --locked --all-targets --tests || exit 1
cargo clippy --locked --all-targets --tests -- -D warnings || exit 1

You will need to chmod +x .git/hooks/pre-commit to have it run on every commit you make.

Certificate of Origin

In order to get a clear contribution chain of trust we use the signed-off-by language used by the Linux kernel project.

Patch format & Git Commit Hygiene

We use Patch as synonym for Commit.

We require patches to:

• Have a Signed-off-by: Name <email> footer
• Follow the pattern: \

   <component>: Change summary
  
   More detailed explanation of your changes: Why and how.
   Wrap it to 72 characters.
   See http://chris.beams.io/posts/git-commit/
   for some more good pieces of advice.
  
   Signed-off-by: <contributor@foo.com>
  

Valid components are listed in TitleStartsWithComponent.py. In short, each cargo workspace member is a valid component as well as build, ci, docs and misc.

Example patch:

vm-virtio: Reset underlying device on driver request
    
If the driver triggers a reset by writing zero into the status register
then reset the underlying device if supported. A device reset also
requires resetting various aspects of the queue.
    
In order to be able to do a subsequent reactivate it is required to
reclaim certain resources (interrupt and queue EventFDs.) If a device
reset is requested by the driver but the underlying device does not
support it then generate an error as the driver would not be able to
configure it anyway.
    
Signed-off-by: Rob Bradford <robert.bradford@intel.com>

Git Commit History

We value a clean, reviewable commit history. Each commit should represent a self-contained, logical step that guides reviewers clearly from A to B.

Avoid patterns like init A -> init B -> fix A or
init design A -> revert A -> use design B. Commits must be independently reviewable - don't leave "fix previous commit" or earlier design attempts in the history.

Intermediate work-in-progress changes are acceptable only if a subsequent commit in the same series cleans them up (e.g. a temporary #[allow(unused)] removed in the next commit).

Pull requests

Cloud Hypervisor uses the “fork-and-pull” development model. Follow these steps if you want to merge your changes to cloud-hypervisor:

1. Fork the cloud-hypervisor project into your github organization.
2. Within your fork, create a branch for your contribution.
3. Create a pull request against the main branch of the Cloud Hypervisor repository.
4. Each commit must comply with the Commit Hygiene guidelines above.
5. A pull request should address a single component or concern to keep review focused and approvals straightforward.
6. Once the pull request is approved it can be integrated.

Please squash any changes done during review already into the corresponding commits instead of pushing <component>: addressing review for A-style commits.

Issue tracking

If you have a problem, please let us know. We recommend using github issues for formally reporting and documenting them.

To quickly and informally bring something up to us, you can also reach out on Slack.

Closing issues

You can either close issues manually by adding the fixing commit SHA1 to the issue comments or by adding the Fixes keyword to your commit message:

serial: Set terminal in raw mode
    
In order to have proper output from the serial, we need to setup the
terminal in raw mode. When the VM is shutting down, it is also the
VMM responsibility to set the terminal back into canonical mode if we
don't want to get any weird behavior from the shell.
    
Fixes #88
	
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>

Then, after the corresponding PR is merged, GitHub will automatically close that issue when parsing the commit message.

AI Generated Code

Our policy is to decline any contributions known to contain contents generated or derived from using Large Language Models (LLMs). This includes ChatGPT, Gemini, Claude, Copilot and similar tools.

The goal is to avoid ambiguity in license compliance and optimize the use of limited project resources, especially for code review and maintenance. This policy can be revisited as LLMs evolve and mature.