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.
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.
We use the Chromium issue tracker. Please use OS>Systems>Containers component.
The following is high level guidance for producing contributions to crosvm.
In the bin/ directory of the crosvm repository, there is the clippy script which lints the Rust code and the fmt script which will format the crosvm Rust code inplace.
The ./test_all script will use docker containers to run all tests for crosvm.
For more details on using the docker containers for running tests locally, including faster, iterative test runs, see ci/README.md.
To format all code, crosvm defers to rustfmt. In addition, the code adheres to the following rules:
The use statements for each module should be grouped in this order
stdcratecrosvm uses the remain crate to keep error enums sorted, along with the #[sorted] attribute to keep their corresponding match statements in the same order.
Since crosvm is one of Chromium OS projects, please read through Chrome OS Contributing Guide first. This section describes the crosvm-specific workflow.
We use Chromium Gerrit for code reviewing. All crosvm CLs are listed at the crosvm component.
Note: We don't accept any pull requests on the GitHub mirror.
If you have already set up the chromiumos repository and the repo command, you can simply create and upload your CL in the same way as other Chromium OS projects.
If you are not interested in other Chromium OS components, you can simply clone and contribute crosvm only. Before you make a commit locally, please set up Gerrit's Change-Id hook on your system.
$ git clone https://chromium.googlesource.com/chromiumos/platform/crosvm # Modify code and make a git commit with a commit message following this rule: # https://chromium.googlesource.com/chromiumos/docs/+/HEAD/contributing.md#Commit-messages $ git commit # Push your commit to Chromium Gerrit (https://chromium-review.googlesource.com/). $ git push origin HEAD:refs/for/main
Your change must be reviewed and approved by one of crosvm owners.
Once your change is reviewed, it will need to go through two layers of presubmit checks.
The review will trigger Kokoro to run crosvm specific tests. If you want to check kokoro results before a review, you can set 'Commit Queue +1' in gerrit to trigger a dry-run.
If you upload further changes after the you were given 'Code Review +2', Kokoro will automatically trigger another test run. But you can also always comment 'kokoro rerun' to manually trigger another build if needed.
When Kokoro passes, it will set Verified +1 and the change is ready to be sent to the ChromeOS commit queue by setting CQ+2.
Note: This is different from other ChromeOS repositories, where Verified +1 bit is set by the developers to indicate that they successfully tested a change. The Verified bit can only be set by Kokoro in the crosvm repository.
Daily job called Pupr will test the new change through the commit queue (see the topic chromeos-base/crosvm for the attempts). The commit queue will test the new crosvm on ChromeOS hardware, including high level end-to-end tests. Only if all of those pass, the pinned version of crosvm (as specified in the CROS_WORKON_COMMIT in crosvm-0.1.0-rXXXX.ebuild) will be used in the Chrome OS build (this is referred to as crosvm uprev process).
Failures here will delay the landing of the change and may cause Google engineers to revert your change. If there is any other change in Chrome OS that crosvm uprev needs to be coordinated, please ask your reviewer and find who is responsible for looking after the uprev so that they can add relevant Cq-Depend and other metadata.
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-depsscript.
cd crosvm/docs/book/ mdbook build
Note: If you make a certain size of changes, it's recommended to reinstall mdbook manually with
cargo install mdbook, as./tools/install-depsonly installs a binary with some convenient features disabled. For example, the full version of mdbook allows you to edit files while checking rendered results.