This article goes into detail about multiple areas of interest to contributors, which includes reviewers, developers, and integrators who each share an interest in guiding crosvm's direction.
We use Google issue tracker. Please use the public crosvm component.
For Googlers: See go/crosvm#filing-bugs.
The following is high level guidance for producing contributions to crosvm.
To format all code, crosvm defers to rustfmt
. In addition, the code adheres to the following rules:
Each use
statement should import a single item, as produced by rustfmt
with imports_granularity=item
. Do not use braces to import multiple items.
The use
statements for each module should be grouped into blocks separated by whitespace in the order produced by rustfmt
with group_imports=StdExternalCrate
and sorted alphabetically:
std
crate
+ super
The import formatting options of rustfmt
are currently unstable, so these are not enforced automatically. If a nightly Rust toolchain is present, it is possible to automatically reformat the code to match these guidelines by running tools/fmt --nightly
.
crosvm uses the remain crate to keep error enums sorted, along with the #[sorted]
attribute to keep their corresponding match statements in the same order.
Unit tests and other highly-specific tests (which may include some small, but not all, integration tests) should be written differently than how non-test code is written. Tests prevent regressions from being committed, show how APIs can be used, and help with understanding bugs in code. That means tests must be clear both now and in the future to a developer with low familiarity of the code under test. They should be understandable by reading from top to bottom without referencing any other code. Towards these goals, tests should:
test_foo_invalid_bar_returns_baz
.Less-specific tests, such as most integration tests and system tests, are more likely to require obfuscating work behind helper methods. It is still good to strive for clarity and ease of debugging in those tests, but they do not need to follow these guidelines.
You need to set up a user account with gerrit. Once logged in, you can obtain HTTP Credentials to set up git to upload changes.
Once set up, run ./tools/cl
to install the gerrit commit message hook. This will insert a unique “Change-Id” into all commit messages so gerrit can identify changes.
Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you‘ve already submitted one (even if it was for a different project), you probably don’t need to do it again.
As for commit messages, we follow ChromeOS's guideline in general.
Here is an example of a good commit message:
devices: vhost: user: vmm: Add Connection type This abstracts away the cross-platform differences: cfg(unix) uses a Unix domain stream socket to connect to the vhost-user backend, and cfg(windows) uses a Tube. BUG=b:249361790 TEST=tools/presubmit --all Change-Id: I47651060c2ce3a7e9f850b7ed9af8bd035f82de6
devices:
or base:
. If you only modified a specific component in a crate, you can specify the path to the component as a tag like devices: vhost: user:
. If your commit modified multiple crates, specify the crate your main change exists. The subject should be no more than 50 characters, including any tags.BUG
lines are used to specify an associated issue number. If the issue is filed at the Google's issue tracker, write BUG=b:<bug number>
. If no issue is associated, write BUG=None
. You can have multiple BUG
lines.TEST
lines are used to describe how you tested your commit in a free form. You can have multiple TEST
lines.Change-Id
is used to identify your change on Gerrit. It‘s inserted by the gerrit commit message hook as explained in the previous section. If a new commit is uploaded with the same Change-Id
with an existing CL’s one, the gerrit will recognize the new commit as a new patchset of the existing CL.To make changes to crosvm, start your work on a new branch tracking origin/main
.
git checkout --branch myfeature --track origin/main
After making the necessary changes, and testing them via Presubmit Checks, you can commit and upload them:
git commit ./tools/cl upload
If you need to revise your change, you can amend the existing commit and upload again:
git commit --amend ./tools/cl upload
This will create a new version of the same change in gerrit.
Note: We don't accept any pull requests on the GitHub mirror.
All submissions needs to be reviewed by one of the crosvm owners. Use the gerrit UI to request a review. If you are uncertain about the correct person to review, reach out to the team via chat or email list.
Crosvm uses a Commit Queue, which will run pre-submit testing on all changes before merging them into crosvm.
Once one of the crosvm owners has voted “Code-Review+2” on your change, you can use the “Submit to CQ” button, which will trigger the test process.
Gerrit will show any test failures. Refer to Building Crosvm for information on how to run the same tests locally.
When all tests pass, your change is merged into origin/main
.
The book of crosvm is build with mdBook. Each markdown files must follow Google Markdown style guide.
To render the book locally, you need to install mdbook and mdbook-mermaid, which should be installed when you run ./tools/install-deps
script. Or you can use the tools/dev_container
environment.
cd docs/book/ mdbook build
Output is found at docs/book/book/html/
.
Note: If you make a certain size of changes, it's recommended to reinstall mdbook manually with
cargo install mdbook
, as./tools/install-deps
only installs a binary with some convenient features disabled. For example, the full version of mdbook allows you to edit files while checking rendered results.