1# Contributing 2 3## Intro 4 5This article goes into detail about multiple areas of interest to contributors, which includes 6reviewers, developers, and integrators who each share an interest in guiding crosvm's direction. 7 8## Contributor License Agreement 9 10Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or 11your employer) retain the copyright to your contribution; this simply gives us permission to use and 12redistribute your contributions as part of the project. Head over to 13<https://cla.developers.google.com/> to see your current agreements on file or to sign a new one. 14 15You generally only need to submit a CLA once, so if you've already submitted one (even if it was for 16a different project), you probably don't need to do it again. 17 18## Bug Reports 19 20We use the Chromium issue tracker. Please use 21[`OS>Systems>Containers`](https://bugs.chromium.org/p/chromium/issues/list?q=component:OS%3ESystems%3EContainers) 22component. 23 24## Philosophy 25 26The following is high level guidance for producing contributions to crosvm. 27 28- Prefer mechanism to policy. 29- Use existing protocols when they are adequate, such as virtio. 30- Prefer security over code re-use and speed of development. 31- Only the version of Rust in use by the Chrome OS toolchain is supported. This is ordinarily the 32 stable version of Rust, but can be behind a version for a few weeks. 33- Avoid distribution specific code. 34 35## Code Health 36 37### Scripts 38 39In the `bin/` directory of the crosvm repository, there is the `clippy` script which lints the Rust 40code and the `fmt` script which will format the crosvm Rust code inplace. 41 42### Running tests 43 44The `./test_all` script will use docker containers to run all tests for crosvm. 45 46For more details on using the docker containers for running tests locally, including faster, 47iterative test runs, see `ci/README.md`. 48 49### Style guidelines 50 51To format all code, crosvm defers to rustfmt. In addition, the code adheres to the following rules: 52 53The `use` statements for each module should be grouped in this order 54 551. `std` 561. third-party crates 571. chrome os crates 581. crosvm crates 591. `crate` 60 61crosvm uses the [remain](https://github.com/dtolnay/remain) crate to keep error enums sorted, along 62with the `#[sorted]` attribute to keep their corresponding match statements in the same order. 63 64## Submitting Code 65 66Since crosvm is one of Chromium OS projects, please read through [Chrome OS Contributing Guide] 67first. This section describes the crosvm-specific workflow. 68 69### Trying crosvm 70 71Please see [the book of crosvm]. 72 73### Sending for code review 74 75We use [Chromium Gerrit](https://chromium-review.googlesource.com/) for code reviewing. All crosvm 76CLs are listed at the [crosvm component]. 77 78> Note: We don't accept any pull requests on the [GitHub mirror]. 79 80#### For Chromium OS Developers {#chromiumos-cl} 81 82If you have already set up the `chromiumos` repository and the `repo` command, you can simply create 83and upload your CL in a similar manner as other Chromium OS projects. 84 85`repo start` will create a branch tracking `cros/chromeos` so you can develop with the latest, 86CQ-tested code as a foundation. 87 88However, changes are not acceped to the `cros/chromeos` branch, and should be submitted to 89`cros/main` instead. 90 91Use `repo upload -D main` to upload changes to the main branch, which works fine in most cases where 92gerrit can rebase the commit cleanly. If not, please rebase to `cros/main` manually. 93 94#### For non-Chromium OS Developers 95 96If you are not interested in other Chromium OS components, you can simply 97[clone and contribute crosvm only](https://google.github.io/crosvm/building_crosvm/linux.html). 98Before you make a commit locally, please set up [Gerrit's Change-Id hook] on your system. 99 100```sh 101# Modify code and make a git commit with a commit message following this rule: 102# https://chromium.googlesource.com/chromiumos/docs/+/HEAD/contributing.md#Commit-messages 103git commit 104# Push your commit to Chromium Gerrit (https://chromium-review.googlesource.com/). 105git push origin HEAD:refs/for/main 106``` 107 108### Code review 109 110Your change must be reviewed and approved by one of [crosvm owners]. 111 112### Presubmit checking {#presubmit} 113 114Once your change is reviewed, it will need to go through two layers of presubmit checks. 115 116The review will trigger Kokoro to run crosvm specific tests. If you want to check kokoro results 117before a review, you can set 'Commit Queue +1' in gerrit to trigger a dry-run. 118 119If you upload further changes after the you were given 'Code Review +2', Kokoro will automatically 120trigger another test run. But you can also always comment 'kokoro rerun' to manually trigger another 121build if needed. 122 123When Kokoro passes, it will set Verified +1 and the change is ready to be sent to the 124[ChromeOS commit queue](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/contributing.md#send-your-changes-to-the-commit-queue) 125by setting CQ+2. 126 127Note: This is different from other ChromeOS repositories, where Verified +1 bit is set by the 128developers to indicate that they successfully tested a change. The Verified bit can only be set by 129Kokoro in the crosvm repository. 130 131### Postsubmit merging to Chrome OS {#chromiumos-postsubmit} 132 133Crosvm has a unique setup to integrate with ChromeOS infrastructure. 134 135The chromeos checkout tracks the 136[cros/chromeos](https://chromium.googlesource.com/chromiumos/platform/crosvm/+/refs/heads/chromeos) 137branch of crosvm, not the 138[cros/main](https://chromium.googlesource.com/chromiumos/platform/crosvm/+/refs/heads/main) branch. 139 140While upstream development is happening on the `main` branch, changes submitted to that branch are 141only tested by the crosvm kokoro CI system, not by the ChromeOS CQ. 142 143There is a 144[daily process](https://chromium-review.googlesource.com/q/project:chromiumos%252Fplatform%252Fcrosvm+branch:chromeos) 145that creates a commit to merge changes from `main` into the `chromeos` branch, which is then tested 146through the CQ and watched by the crosvm-uprev rotation. 147 148## Contributing to the documentation 149 150[The book of crosvm] is build with [mdBook]. Each markdown files must follow 151[Google Markdown style guide]. 152 153To render the book locally, you need to install mdbook and [mdbook-mermaid], which should be 154installed when you run `./tools/install-deps`script. 155 156```sh 157cd crosvm/docs/book/ 158mdbook build 159``` 160 161> Note: If you make a certain size of changes, it's recommended to reinstall mdbook manually with 162> `cargo install mdbook`, as `./tools/install-deps` only installs a binary with some convenient 163> features disabled. For example, the full version of mdbook allows you to edit files while checking 164> rendered results. 165 166[chrome os contributing guide]: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/contributing.md 167[crosvm component]: https://chromium-review.googlesource.com/q/project:chromiumos%252Fplatform%252Fcrosvm 168[crosvm owners]: https://chromium.googlesource.com/chromiumos/platform/crosvm/+/HEAD/OWNERS 169[gerrit's change-id hook]: https://gerrit-review.googlesource.com/Documentation/user-changeid.html 170[github mirror]: https://github.com/google/crosvm 171[google markdown style guide]: https://github.com/google/styleguide/blob/gh-pages/docguide/style.md 172[mdbook]: https://rust-lang.github.io/mdBook/ 173[mdbook-mermaid]: https://github.com/badboy/mdbook-mermaid 174[the book of crosvm]: https://google.github.io/crosvm/ 175