1# Coding guidelines
2
3For the most part, Wasmtime and Cranelift follow common Rust conventions and
4[pull request] (PR) workflows, though we do have a few additional things to
5be aware of.
6
7[pull request]: https://help.github.com/articles/about-pull-requests/
8
9### `rustfmt`
10
11All PRs must be formatted according to rustfmt, and this is checked in the
12continuous integration tests. You can format code locally with:
13
14```sh
15$ cargo fmt
16```
17
18at the root of the repository. You can find [more information about rustfmt
19online](https://github.com/rust-lang/rustfmt) too, such as how to configure
20your editor.
21
22### Minimum Supported `rustc` Version
23
24Wasmtime and Cranelift support the latest three stable releases of Rust. This
25means that if the latest version of Rust is 1.72.0 then Wasmtime supports Rust
261.70.0, 1.71.0, and 1.72.0. CI will test by default with 1.72.0 and there will
27be one job running the full test suite on Linux x86\_64 on 1.70.0.
28
29Some of the CI jobs depend on nightly Rust, for example to run rustdoc with
30nightly features, however these use pinned versions in CI that are updated
31periodically and the general repository does not depend on nightly features.
32
33Updating Wasmtime's MSRV is done by editing the `rust-version` field in the
34workspace root's `Cargo.toml`
35
36### Dependencies of Wasmtime
37
38Wasmtime and Cranelift have a higher threshold than default for adding
39dependencies to the project. All dependencies are required to be "vetted"
40through the [`cargo vet` tool](https://mozilla.github.io/cargo-vet/). This is
41checked on CI and will run on all modifications to `Cargo.lock`.
42
43A "vet" for Wasmtime is not a meticulous code review of a dependency for
44correctness but rather it is a statement that the crate does not contain
45malicious code and is safe for us to run during development and (optionally)
46users to run when they run Wasmtime themselves. Wasmtime's vet entries are used
47by other organizations which means that this isn't simply for our own personal
48use. Wasmtime additionally uses vet entries from other organizations as well
49which means we don't have to vet everything ourselves.
50
51New vet entries are required to be made by trusted contributors to Wasmtime.
52This is all configured in the `supply-chain` folder of Wasmtime. These files
53generally aren't hand-edited though and are instead managed through the `cargo
54vet` tool itself. Note that our `supply-chain/audits.toml` additionally contains
55entries which indicates that authors are trusted as opposed to vets of
56individual crates. This lowers the burden of updating version of a crate from a
57trusted author.
58
59When put together this means that contributions to Wasmtime and Cranelift which
60update existing dependencies or add new dependencies will not be mergeable by
61default (CI will fail). This is expected from our project's configuration and
62this situation will be handled one of a few ways:
63
64* If a new dependency is being added it might be worth trying to slim down
65  what's required or avoiding the dependency altogether. Avoiding new
66  dependencies is best when reasonable, but it is not always reasonable to do
67  so. This is left to the judgement of the author and reviewer.
68
69* When updating dependencies this should be done for a specific purpose relevant
70  to the PR-at-hand. For example if the PR implements a new feature then the
71  dependency update should be required for the new feature. Otherwise it's best
72  to leave dependency updates to their own PRs. It's ok to update dependencies
73  "just for the update" but we prefer to have that as separate PRs.
74
75* If a new dependency or dependency update is required, then a trusted
76  contributor of Wasmtime will be required to perform a vet of the new
77  crate/version. This will be done through a separate PR to Wasmtime so we ask
78  contributors to not run `cargo vet` themselves to get CI passing. Reviewers
79  understand what `cargo vet` failures are on CI and how it doesn't reflect on
80  the quality of the PR itself. Once the reviewer (or another maintainer) merges
81  a PR adding the vet entries necessary for the original contribution it can be
82  rebased to get CI passing.
83
84Note that this process is not in place to prevent new dependencies or prevent
85updates, but rather it ensures that development of Wasmtime is done with a
86trusted set of code that has been reviewed by trusted parties. We welcome
87dependency updates and new functionality, so please don't be too alarmed when
88contributing and seeing a failure of `cargo vet` on CI!
89