1# How to Contribute to crosvm 2 3## How to report bugs 4 5We use Google issue tracker. Please use 6[the public crosvm component](https://issuetracker.google.com/issues?q=status:open%20componentid:1161302). 7 8**For Googlers**: See [go/crosvm#filing-bugs](https://goto.google.com/crosvm#filing-bugs). 9 10## Contributing code 11 12### Gerrit Account 13 14You need to set up a user account with [gerrit](https://chromium-review.googlesource.com/). Once 15logged in, you can obtain 16[HTTP Credentials](https://chromium-review.googlesource.com/settings/#HTTPCredentials) to set up git 17to upload changes. 18 19Once set up, run `./tools/cl` to install the gerrit commit message hook. This will insert a unique 20"Change-Id" into all commit messages so gerrit can identify changes. Even warning messages appear, 21the message hook will be installed. 22 23### Contributor License Agreement 24 25Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or 26your employer) retain the copyright to your contribution; this simply gives us permission to use and 27redistribute your contributions as part of the project. Head over to 28<https://cla.developers.google.com/> to see your current agreements on file or to sign a new one. 29 30You generally only need to submit a CLA once, so if you've already submitted one (even if it was for 31a different project), you probably don't need to do it again. 32 33### Commit Messages 34 35As for commit messages, we follow 36[ChromeOS's guideline](https://www.chromium.org/chromium-os/developer-library/guides/development/contributing/#commit-messages) 37in general. 38 39Here is an example of a good commit message: 40 41``` 42devices: vhost: user: vmm: Add Connection type 43 44This abstracts away the cross-platform differences: 45cfg(any(target_os = "android", target_os = "linux")) uses a Unix 46domain domain stream socket to connect to the vhost-user backend, and 47cfg(windows) uses a Tube. 48 49BUG=b:249361790 50TEST=tools/presubmit --all 51 52Change-Id: I47651060c2ce3a7e9f850b7ed9af8bd035f82de6 53``` 54 55- The first line is a subject that starts with a tag that represents which components your commit 56 relates to. Tags are usually the name of the crate you modified such as `devices:` or `base:`. If 57 you only modified a specific component in a crate, you can specify the path to the component as a 58 tag like `devices: vhost: user:`. If your commit modified multiple crates, specify the crate where 59 your main change exists. The subject should be no more than 50 characters, including any tags. 60- The body should consist of a motivation followed by an impact/action. The body text should be 61 wrapped to 72 characters. 62- `BUG` lines are used to specify an associated issue number. If the issue is filed at 63 [Google's issue tracker](https://issuetracker.google.com/), write `BUG=b:<bug number>`. If no 64 issue is associated, write `BUG=None`. You can have multiple `BUG` lines. 65- `TEST` lines are used to describe how you tested your commit in a free form. You can have multiple 66 `TEST` lines. 67- `Change-Id` is used to identify your change on Gerrit. It's inserted by the gerrit commit message 68 hook as explained in 69 [the previous section](https://crosvm.dev/book/contributing/index.html#gerrit-account). If a new 70 commit is uploaded with the same `Change-Id` as an existing CL's `Change-Id`, gerrit will 71 recognize the new commit as a new patchset of the existing CL. 72 73### Uploading changes 74 75To make changes to crosvm, start your work on a new branch tracking `origin/main`. 76 77```bash 78git checkout -b myfeature --track origin/main 79``` 80 81After making the necessary changes, and testing them via 82[Presubmit Checks](https://crosvm.dev/book/building_crosvm/linux.html#presubmit-checks), you can 83commit and upload them: 84 85```bash 86git commit 87./tools/cl upload 88``` 89 90If you need to revise your change, you can amend the existing commit and upload again: 91 92```bash 93git commit --amend 94./tools/cl upload 95``` 96 97This will create a new version of the same change in gerrit. 98 99If the branch contains multiple commits, each one will be uploaded as a separate review, and they 100will be linked in Gerrit as [related changes]. You may revise any commit in a branch using tools 101like `git rebase` and then re-upload the whole series with `./tools/cl upload` when `HEAD` is 102pointing to the tip of the branch. 103 104> Note: We don't accept any pull requests on the [GitHub mirror]. 105 106### Getting Reviews 107 108All submissions needs to be reviewed by one of the [crosvm owners]. Use the gerrit UI to request a 109review. If you are uncertain about the correct person to review, reach out to the team via 110[chat](https://matrix.to/#/#crosvm:matrix.org) or 111[email list](https://groups.google.com/a/chromium.org/g/crosvm-dev). 112 113### Submitting code 114 115Crosvm uses a Commit Queue, which will run pre-submit testing on all changes before merging them 116into crosvm. 117 118Once one of the [crosvm owners] has voted "Code-Review+2" on your change, you can use the "Submit to 119CQ" button, which will trigger the test process. 120 121Gerrit will show any test failures. Refer to 122[Building Crosvm](https://crosvm.dev/book/building_crosvm/) for information on how to run the same 123tests locally. 124 125Each individual change in a patch series must build and pass the tests. If you are working on a 126series of related changes, ensure that each incremental commit does not cause test regressions or 127break the build if it is merged without the later changes in the series. For example, an 128intermediate change must not trigger any unused code warnings or cause test failures that are fixed 129by later changes in the series. 130 131When all tests pass, your change is merged into `origin/main`. 132 133## Contributing to the documentation 134 135[The book of crosvm] is built with [mdBook]. Each markdown file must follow 136[Google Markdown style guide]. 137 138To render the book locally, you need to install mdbook and [mdbook-mermaid], which should be 139installed when you run `./tools/install-deps` script. Or you can use the `tools/dev_container` 140environment. 141 142```sh 143cd docs/book/ 144mdbook build 145``` 146 147Output is found at `docs/book/book/html/`. 148 149To format markdown files, run `./tools/fmt` in the `dev_container`. 150 151[crosvm owners]: https://chromium.googlesource.com/crosvm/crosvm/+/HEAD/OWNERS 152[github mirror]: https://github.com/google/crosvm 153[google markdown style guide]: https://github.com/google/styleguide/blob/gh-pages/docguide/style.md 154[mdbook]: https://rust-lang.github.io/mdBook/ 155[mdbook-mermaid]: https://github.com/badboy/mdbook-mermaid 156[related changes]: https://gerrit-review.googlesource.com/Documentation/user-review-ui.html#related-changes 157[the book of crosvm]: https://crosvm.dev/book/ 158