bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

add 'project' process guidlines for larger contributions

Browse source
This commit is contained in:
Ralf Jung 2024-08-15 22:45:10 +02:00
parent f25ca7eca8
commit 293be4611d
1 changed files with 34 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

35
src/tools/miri/CONTRIBUTING.md
View file

@ -8,10 +8,43 @@ find useful.
Check out the issues on this GitHub repository for some ideas. In particular, 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 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 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 [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 ## Preparing the build environment
Miri heavily relies on internal and unstable rustc interfaces to execute MIR, Miri heavily relies on internal and unstable rustc interfaces to execute MIR,