|
1 | 1 | # Crater |
2 | 2 |
|
3 | 3 | [Crater](https://github.com/rust-lang/crater) is a tool for compiling and |
4 | | -running tests for _every_ crate on [crates.io](https://crates.io) (and a few on |
5 | | -GitHub). It is mainly used for checking the extent of breakage when implementing |
| 4 | +running tests for _every_ crate on [crates.io](https://crates.io) (and a few on GitHub). |
| 5 | +It is mainly used for checking the extent of breakage when implementing |
6 | 6 | potentially breaking changes and ensuring lack of breakage by running beta vs |
7 | 7 | stable compiler versions. |
8 | 8 |
|
9 | 9 | ## When to run Crater |
10 | 10 |
|
11 | 11 | You should request a Crater run if your PR makes large changes to the compiler |
12 | | -or could cause breakage. If you are unsure, feel free to ask your PR's reviewer. |
| 12 | +or could cause breakage. |
| 13 | +If you are unsure, feel free to ask your PR's reviewer. |
13 | 14 |
|
14 | 15 | ## Requesting Crater Runs |
15 | 16 |
|
16 | 17 | The Rust team maintains a few machines that can be used for Crater runs |
17 | | -on the changes introduced by a PR. If your PR needs a Crater run, leave a |
18 | | -comment for the triage team in the PR thread. Please inform the team whether you |
19 | | -require a "check-only" Crater run, a "build only" Crater run, or a |
20 | | -"build-and-test" Crater run. The difference is primarily in time; |
21 | | -if you're not sure, go for the build-and-test run. If |
22 | | -making changes that will only have an effect at compile-time (e.g., implementing |
23 | | -a new trait), then you only need a check run. |
24 | | - |
25 | | -Your PR will be enqueued by the triage team and the results will be posted when |
26 | | -they are ready. Check runs will take around ~3-4 days, and the other two taking |
27 | | -5-6 days on average. |
28 | | - |
29 | | -While Crater is really useful, it is also important to be aware of a few |
30 | | -caveats: |
31 | | - |
32 | | -- Not all code is on crates.io! There is a lot of code in repos on GitHub and |
33 | | - elsewhere. Also, companies may not wish to publish their code. Thus, a |
34 | | - successful Crater run does not mean there will be no |
| 18 | +on the changes introduced by a PR. |
| 19 | +If your PR needs a Crater run, leave a comment for the triage team in the PR thread. |
| 20 | +Please inform the team whether you |
| 21 | +require a "check-only" Crater run, a "build only" Crater run, or a "build-and-test" Crater run. |
| 22 | +The difference is primarily in time; |
| 23 | +if you're not sure, go for the build-and-test run. |
| 24 | +If making changes that will only have an effect at compile-time |
| 25 | +(e.g., implementing a new trait), then you only need a check run. |
| 26 | + |
| 27 | +Your PR will be enqueued by the triage team and the results will be posted when they are ready. |
| 28 | +Check runs will take around ~3-4 days, and the other two taking 5-6 days on average. |
| 29 | + |
| 30 | +While Crater is really useful, it is also important to be aware of a few caveats: |
| 31 | + |
| 32 | +- Not all code is on crates.io! |
| 33 | + There is a lot of code in repos on GitHub and elsewhere. |
| 34 | + Also, companies may not wish to publish their code. |
| 35 | + Thus, a successful Crater run does not mean there will be no |
35 | 36 | breakage; you still need to be careful. |
36 | 37 |
|
37 | | -- Crater only runs Linux builds on x86_64. Thus, other architectures and |
38 | | - platforms are not tested. Critically, this includes Windows. |
| 38 | +- Crater only runs Linux builds on x86_64. Thus, other architectures and platforms are not tested. |
| 39 | + Critically, this includes Windows. |
39 | 40 |
|
40 | | -- Many crates are not tested. This could be for a lot of reasons, including that |
| 41 | +- Many crates are not tested. |
| 42 | + This could be for a lot of reasons, including that |
41 | 43 | the crate doesn't compile any more (e.g. used old nightly features), has |
42 | 44 | broken or flaky tests, requires network access, or other reasons. |
43 | 45 |
|
|
0 commit comments