1# Contributing to Cloud Hypervisor 2 3Cloud Hypervisor is an open source project licensed under the [Apache v2 4License](https://opensource.org/licenses/Apache-2.0) and the [BSD 3 5Clause](https://opensource.org/licenses/BSD-3-Clause) license. Individual files 6contain details of their licensing and changes to that file are under the same 7license unless the contribution changes the license of the file. When importing 8code from a third party project (e.g. Firecracker or crosvm) please respect the 9license of those projects. 10 11New code should be under the [Apache v2 12License](https://opensource.org/licenses/Apache-2.0). 13 14## Coding Style 15 16We follow the [Rust Style](https://github.com/rust-lang/rust/tree/HEAD/src/doc/style-guide/src) 17convention and enforce it through the Continuous Integration (CI) process calling into `rustfmt` 18for each submitted Pull Request (PR). 19 20## Basic Checks 21 22Please consider creating the following hook as `.git/hooks/pre-commit` in order 23to ensure basic correctness of your code. You can extend this further if you 24have specific features that you regularly develop against. 25 26```sh 27#!/bin/sh 28 29cargo fmt -- --check || exit 1 30cargo check --locked --all --all-targets --tests || exit 1 31cargo clippy --locked --all --all-targets --tests -- -D warnings || exit 1 32``` 33 34You will need to `chmod +x .git/hooks/pre-commit` to have it run on every 35commit you make. 36 37## Certificate of Origin 38 39In order to get a clear contribution chain of trust we use the [signed-off-by language](https://web.archive.org/web/20230406041855/https://01.org/community/signed-process) 40used by the Linux kernel project. 41 42## Patch format 43 44Beside the signed-off-by footer, we expect each patch to comply with the following format: 45 46``` 47<component>: Change summary 48 49More detailed explanation of your changes: Why and how. 50Wrap it to 72 characters. 51See http://chris.beams.io/posts/git-commit/ 52for some more good pieces of advice. 53 54Signed-off-by: <contributor@foo.com> 55``` 56 57For example: 58 59``` 60vm-virtio: Reset underlying device on driver request 61 62If the driver triggers a reset by writing zero into the status register 63then reset the underlying device if supported. A device reset also 64requires resetting various aspects of the queue. 65 66In order to be able to do a subsequent reactivate it is required to 67reclaim certain resources (interrupt and queue EventFDs.) If a device 68reset is requested by the driver but the underlying device does not 69support it then generate an error as the driver would not be able to 70configure it anyway. 71 72Signed-off-by: Rob Bradford <robert.bradford@intel.com> 73``` 74 75## Pull requests 76 77Cloud Hypervisor uses the “fork-and-pull” development model. Follow these steps if 78you want to merge your changes to `cloud-hypervisor`: 79 801. Fork the [cloud-hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) project 81 into your github organization. 821. Within your fork, create a branch for your contribution. 831. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) 84 against the main branch of the Cloud Hypervisor repository. 851. To update your pull request amend existing commits whenever applicable and 86 then push the new changes to your pull request branch. 871. Once the pull request is approved it can be integrated. 88 89## Issue tracking 90 91If you have a problem, please let us know. We recommend using 92[github issues](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/new) for formally 93reporting and documenting them. 94 95To quickly and informally bring something up to us, you can also reach out on [Slack](https://cloud-hypervisor.slack.com). 96 97## Closing issues 98 99You can either close issues manually by adding the fixing commit SHA1 to the issue 100comments or by adding the `Fixes` keyword to your commit message: 101 102``` 103serial: Set terminal in raw mode 104 105In order to have proper output from the serial, we need to setup the 106terminal in raw mode. When the VM is shutting down, it is also the 107VMM responsibility to set the terminal back into canonical mode if we 108don't want to get any weird behavior from the shell. 109 110Fixes #88 111 112Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com> 113``` 114 115Then, after the corresponding PR is merged, GitHub will automatically close that issue when parsing the 116[commit message](https://help.github.com/articles/closing-issues-via-commit-messages/). 117