diff options
| -rw-r--r-- | src/tools/miri/CONTRIBUTING.md | 35 |
1 files changed, 34 insertions, 1 deletions
diff --git a/src/tools/miri/CONTRIBUTING.md b/src/tools/miri/CONTRIBUTING.md index 1c76354eaee..ca03a9b16e3 100644 --- a/src/tools/miri/CONTRIBUTING.md +++ b/src/tools/miri/CONTRIBUTING.md @@ -8,10 +8,43 @@ find useful. Check out the issues on this GitHub repository for some ideas. In particular, look for the green `E-*` labels which mark issues that should be rather well-suited for onboarding. For more ideas or help with hacking on Miri, you can -contact us (`oli-obk` and `RalfJ`) on the [Rust Zulip]. +contact us on the [Rust Zulip]. See the [Rust website](https://www.rust-lang.org/governance/teams/compiler#team-miri) +for a list of Miri maintainers. [Rust Zulip]: https://rust-lang.zulipchat.com +### Larger-scale contributions + +If you are thinking about making a larger-scale contribution -- in particular anything that needs +more than can reasonably fit in a single PR to be feature-complete -- then please talk to us before +writing significant amounts of code. Generally, we will ask that you follow a three-step "project" +process for such contributions: + +1. Clearly define the **goal** of the project. This defines the scope of the project, i.e. which + part of which APIs should be supported. If this involves functions that expose a big API surface + with lots of flags, the project may want to support only a tiny subset of flags; that should be + documented. A good way to express the goal is with one or more test cases that Miri should be + able to successfully execute when the project is completed. It is a good idea to get feedback + from team members already at this stage to ensure that the project is reasonably scoped and + aligns with our interests. +2. Make a **design** for how to realize the goal. A larger project will likely have to do global + changes to Miri, like adding new global state to the `Machine` type or new methods to the + `FileDescription` trait. Often we have to iterate on those changes, which can quite substantially + change how the final implementation looks like. + + The design should be reasonably concrete, i.e. for new global state or methods the corresponding + Rust types and method signatures should be spelled out. We realize that it can be hard to make a + design without doing implementation work, in particular if you are not yet familiar with the + codebase. Doing draft implementations in phase 2 of this process is perfectly fine, just please + be aware that we might request fundamental changes that can require significantly reworking what + you already did. If you open a PR in this stage, please clearly indicate that this project is + still in the design stage. + +3. Finish the **implementation** and have it reviewed. + +This process is largely informal, and its primary goal is to more clearly communicate expectations. +Please get in touch with us if you have any questions! + ## Preparing the build environment Miri heavily relies on internal and unstable rustc interfaces to execute MIR, |