Skip to content

Commit

Permalink
Document cargo vet in contributing docs (#7635)
Browse files Browse the repository at this point in the history
I realized just now that we haven't actually documented our usage of
`cargo vet` anywhere in our contributing documentation (or not that I
could find), so I decided to try and rectify that!
  • Loading branch information
alexcrichton authored Dec 5, 2023
1 parent f41a252 commit 5c8bce7
Show file tree
Hide file tree
Showing 3 changed files with 61 additions and 8 deletions.
54 changes: 53 additions & 1 deletion docs/contributing-coding-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,56 @@ periodically and the general repository does not depend on nightly features.
Updating Wasmtime's MSRV is done by editing the `rust-version` field in the
workspace root's `Cargo.toml`

[Rust Update Policy for Firefox]: https://wiki.mozilla.org/Rust_Update_Policy_for_Firefox#Schedule
### Dependencies of Wasmtime

Wasmtime and Cranelift have a higher threshold than default for adding
dependencies to the project. All dependencies are required to be "vetted"
through the [`cargo vet` tool](https://mozilla.github.io/cargo-vet/). This is
checked on CI and will run on all modifications to `Cargo.lock`.

A "vet" for Wasmtime is not a meticulous code review of a dependency for
correctness but rather it is a statement that the crate does not contain
malicious code and is safe for us to run during development and (optionally)
users to run when they run Wasmtime themselves. Wasmtime's vet entries are used
by other organizations which means that this isn't simply for our own personal
use. Wasmtime additionally uses vet entries from other organizations as well
which means we don't have to vet everything ourselves.

New vet entries are required to be made by trusted contributors to Wasmtime.
This is all configured in the `supply-chain` folder of Wasmtime. These files
generally aren't hand-edited though and are instead managed through the `cargo
vet` tool itself. Note that our `supply-chain/audits.toml` additionally contains
entries which indicates that authors are trusted as opposed to vets of
individual crates. This lowers the burden of updating version of a crate from a
trusted author.

When put together this means that contributions to Wasmtime and Cranelift which
update existing dependencies or add new dependencies will not be mergeable by
default (CI will fail). This is expected from our project's configuration and
this situation will be handled one of a few ways:

* If a new dependency is being added it might be worth trying to slim down
what's required or avoiding the dependency altogether. Avoiding new
dependencies is best when reasonable, but it is not always reasonable to do
so. This is left to the judgement of the author and reviewer.

* When updating dependencies this should be done for a specific purpose relevant
to the PR-at-hand. For example if the PR implements a new feature then the
dependency update should be required for the new feature. Otherwise it's best
to leave dependency updates to their own PRs. It's ok to update dependencies
"just for the update" but we prefer to have that as separate PRs.

* If a new dependency or dependency update is required, then a trusted
contributor of Wasmtime will be required to perform a vet of the new
crate/version. This will be done through a separate PR to Wasmtime so we ask
contributors to not run `cargo vet` themselves to get CI passing. Reviewers
understand what `cargo vet` failures are on CI and how it doesn't reflect on
the quality of the PR itself. Once the reviewer (or another maintainer) merges
a PR adding the vet entries necessary for the original contribution it can be
rebased to get CI passing.

Note that this process is not in place to prevent new dependencies or prevent
updates, but rather it ensures that development of Wasmtime is done with a
trusted set of code that has been reviewed by trusted parties. We welcome
dependency updates and new functionality, so please don't be too alarmed when
contributing and seeing a failure of `cargo vet` on CI!
7 changes: 0 additions & 7 deletions supply-chain/README

This file was deleted.

8 changes: 8 additions & 0 deletions supply-chain/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Wasmtime's Configuration of `cargo vet`

This directory contains the state for [`cargo vet`], a tool to help projects
ensure that third-party Rust dependencies have been audited by a trusted entity.
For more information about Wasmtime's usage of `cargo vet` see our
[documentation](https://docs.wasmtime.dev/contributing-coding-guidelines.html#dependencies-of-wasmtime).

[`cargo vet`]: https://mozilla.github.io/cargo-vet/

0 comments on commit 5c8bce7

Please sign in to comment.