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
64Note that this process is not in place to prevent new dependencies or prevent
65updates, but rather it ensures that development of Wasmtime is done with a
66trusted set of code that has been reviewed by trusted parties. We welcome
67dependency updates and new functionality, so please don't be too alarmed when
68contributing and seeing a failure of `cargo vet` on CI!
69
70### `cargo vet` for Contributors
71
72If you're a contributor to Wasmtime and you've landed on this documentation,
73hello and thanks for your contribution! Here's some guidelines for changing the
74set of dependencies in Wasmtime:
75
76* If a new dependency is being added it might be worth trying to slim down
77  what's required or avoiding the dependency altogether. Avoiding new
78  dependencies is best when reasonable, but it is not always reasonable to do
79  so. This is left to the judgement of the author and reviewer.
80
81* When updating dependencies this should be done for a specific purpose relevant
82  to the PR-at-hand. For example if the PR implements a new feature then the
83  dependency update should be required for the new feature. Otherwise it's best
84  to leave dependency updates to their own PRs. It's ok to update dependencies
85  "just for the update" but we prefer to have that as separate PRs.
86
87Dependency additions or updates require action on behalf of project maintainers
88so we ask that you don't run `cargo vet` yourself or update the `supply-chain`
89folder yourself. Instead a maintainer will review your PR and perform the `cargo
90vet` entries themselves. Reviewers will typically make a separate pull request
91to add `cargo vet` entries and once that lands yours will be added to the queue.
92
93### `cargo vet` for Maintainers
94
95Maintainers of Wasmtime are required to explicitly vet and approve all
96dependency updates and modifications to Wasmtime. This means that when reviewing
97a PR you should ensure that contributors are not modifying the `supply-chain`
98directory themselves outside of commits authored by other maintainers. Otherwise
99though to add vet entries this is done through one of a few methods:
100
101* For a PR where maintainers themselves are modifying dependencies the `cargo
102  vet` entries can be included inline with the PR itself by the author. The
103  reviewer knows that the author of the PR is themself a maintainer.
104
105* PRs that "just update dependencies" are ok to have at any time. You can do
106  this in preparation for a future feature or for a future contributor. This
107  more-or-less is the same as the previous categories.
108
109* For contributors who should not add vet entries themselves maintainers should
110  review the PR and add vet entries either in a separate PR or as part of the
111  contributor's PR itself. As a separate PR you'll check out the branch, run
112  `cargo vet`, then rebase away the contributor's commits and push your `cargo
113  vet` commit alone to merge. For pushing directly to the contributor's own PR
114  be sure to read the notes below.
115
116Note for the last case it's important to ensure that if you push directly to a
117contributor's PR any future updates pushed by the contributor either contain or
118don't overwrite your vet entries. Also verify that if the PR branch is rebased
119or force-pushed, the details of your previously pushed vetting remain the same:
120e.g., versions were not bumped and descriptive reasons remain the same. If
121pushing a vetting commit to a contributor's PR and also asking for more changes,
122request that the contributor make the requested fixes in an additional commit
123rather than force-pushing a rewritten history, so your existing vetting commit
124remains untouched. These guidelines make it easier to verify no tampering has
125occurred.
126
127### Policy for adding `cargo vet` entries
128
129For maintainers this is intended to document the project's policy on adding
130`cargo vet` entries. The goal of this policy is to not make dependency updates
131so onerous that they never happen while still achieving much of the intended
132benefit of `cargo vet` in protection against supply-chain style attacks.
133
134* For dependencies **that receive at least 10,000 downloads a day** on crates.io
135  it's ok to add an entry to `exemptions` in `supply-chain/config.toml`. This
136  does not require careful review or review at all of these dependencies. The
137  assumption here is that a supply chain attack against a popular crate is
138  statistically likely to be discovered relatively quickly. Changes to `main` in
139  Wasmtime take at least 2 weeks to be released due to our release process, so
140  the assumption is that popular crates that are victim of a supply chain attack
141  would be discovered during this time. This policy additionally greatly helps
142  when updating dependencies on popular crates that are common to see without
143  increasing the burden too much on maintainers.
144
145* For other dependencies a manual vet is required. The `cargo vet` tool will
146  assist in adding a vet by pointing you towards the source code, as published
147  on crates.io, to be browsed online. Manual review should be done to ensure
148  that "nothing nefarious" is happening. For example `unsafe` should be
149  inspected as well as use of ambient system capabilities such as `std::fs`,
150  `std::net`, or `std::process`, and build scripts. Note that you're not
151  reviewing for correctness, instead only for whether a supply-chain attack
152  appears to be present.
153
154This policy intends to strike a rough balance between usability and security.
155It's always recommended to add vet entries where possible, but the first bullet
156above can be used to update an `exemptions` entry or add a new entry. Note that
157when the "popular threshold" is used **do not add a vet entry** because the
158crate is, in fact, not vetted. This is required to go through an
159`[[exemptions]]` entry.
160