crosvm/CONTRIBUTING.md

## Intro

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.

## Guidelines

The following is high level guidance for producing contributions to crosvm.

- Prefer mechanism to policy.
- Use existing protocols when they are adequate, such as virtio.
- Prefer security over code re-use and speed of development.
- Only the version of Rust in use by the Chrome OS toolchain is supported. This is ordinarily the stable version of Rust, but can be behind a version for a few weeks.
- Avoid distribution specific code.

## Code Health

### Scripts

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. When submitting changes, the `bin/smoke_test` script, which checks Rust format and unit tests, will be run by Kokoro, the internal Google run cloud builder, and the results will be posted to the change. Kokoro is only informational, so if Kokoro rejects a change, it can still be submitted.

###  Submitting Code

See also, [Chrome OS Contributing Guide](https://chromium.googlesource.com/chromiumos/docs/+/master/contributing.md)

When a change is approved, verified, and added to the [commit queue](https://chromium.googlesource.com/chromiumos/docs/+/master/contributing.md#send-your-changes-to-the-commit-queue), crosvm will be built and the unit tests (with some exceptions) will be run by the Chrome OS infrastructure. Only if that passes, will the change be submitted. Failures here will cause the commit queue to reject the change until it is re-added (CQ+2). Unfortunately, it is extremely common for false negatives to cause a change to get rejected, so be ready to re-apply the CQ+2 label if you're the owner of a ready to submit change.

### Style guidelines

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

1.  `std`
2. third-party crates
3. chrome os crates
4. crosvm crates
5. `crate`

crosvm uses the [remain](https://github.com/dtolnay/remain) crate to keep error enums sorted, along with the `#[sorted]` attribute to keep their corresponding match statements in the same order.
flesh out high level documentation This change adds a CONTRIBUTING.md and some architectural documentation for people new to submitting code to crosvm. TEST=check the gittiles markdown BUG=None Change-Id: Ib792220ae50329413f487c5d87b29ad3b2f7c59c Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/crosvm/+/2013213 Tested-by: Zach Reizner <zachr@chromium.org> Reviewed-by: Stephen Barber <smbarber@chromium.org> Commit-Queue: Stephen Barber <smbarber@chromium.org> Auto-Submit: Zach Reizner <zachr@chromium.org> 2020-01-21 18:44:09 +00:00			`## Intro`

			`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.`

			`## Guidelines`

			`The following is high level guidance for producing contributions to crosvm.`

			`- Prefer mechanism to policy.`
			`- Use existing protocols when they are adequate, such as virtio.`
			`- Prefer security over code re-use and speed of development.`
			`- Only the version of Rust in use by the Chrome OS toolchain is supported. This is ordinarily the stable version of Rust, but can be behind a version for a few weeks.`
			`- Avoid distribution specific code.`

			`## Code Health`

			`### Scripts`

			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. When submitting changes, the `bin/smoke_test` script, which checks Rust format and unit tests, will be run by Kokoro, the internal Google run cloud builder, and the results will be posted to the change. Kokoro is only informational, so if Kokoro rejects a change, it can still be submitted.

			`### Submitting Code`

			`See also, [Chrome OS Contributing Guide](https://chromium.googlesource.com/chromiumos/docs/+/master/contributing.md)`

			When a change is approved, verified, and added to the [commit queue](https://chromium.googlesource.com/chromiumos/docs/+/master/contributing.md#send-your-changes-to-the-commit-queue), crosvm will be built and the unit tests (with some exceptions) will be run by the Chrome OS infrastructure. Only if that passes, will the change be submitted. Failures here will cause the commit queue to reject the change until it is re-added (CQ+2). Unfortunately, it is extremely common for false negatives to cause a change to get rejected, so be ready to re-apply the CQ+2 label if you're the owner of a ready to submit change.

			`### Style guidelines`

			`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

			1. `std`
			`2. third-party crates`
			`3. chrome os crates`
			`4. crosvm crates`
			5. `crate`

			crosvm uses the [remain](https://github.com/dtolnay/remain) crate to keep error enums sorted, along with the `#[sorted]` attribute to keep their corresponding match statements in the same order.