| # Crater | |
| [Crater](https://github.com/rust-lang/crater) is a tool for compiling and | |
| running tests for _every_ crate on [crates.io](https://crates.io) (and a few on GitHub). | |
| It is mainly used for checking the extent of breakage when implementing | |
| potentially breaking changes and ensuring lack of breakage by running beta vs | |
| stable compiler versions. | |
| ## When to run Crater | |
| You should request a Crater run if your PR makes large changes to the compiler | |
| or could cause breakage. | |
| If you are unsure, feel free to ask your PR's reviewer. | |
| ## Requesting Crater Runs | |
| The Rust team maintains a few machines that can be used for Crater runs | |
| on the changes introduced by a PR. | |
| If your PR needs a Crater run, leave a comment for the triage team in the PR thread. | |
| Please inform the team whether you | |
| require a "check-only" Crater run, a "build only" Crater run, or a "build-and-test" Crater run. | |
| The difference is primarily in time; | |
| if you're not sure, go for the build-and-test run. | |
| If making changes that will only have an effect at compile-time | |
| (e.g., implementing a new trait), then you only need a check run. | |
| Your PR will be enqueued by the triage team and the results will be posted when they are ready. | |
| Check runs will take around ~3-4 days, and the other two taking 5-6 days on average. | |
| While Crater is really useful, it is also important to be aware of a few caveats: | |
| - Not all code is on crates.io! | |
| There is a lot of code in repos on GitHub and elsewhere. | |
| Also, companies may not wish to publish their code. | |
| Thus, a successful Crater run does not mean there will be no | |
| breakage; you still need to be careful. | |
| - Crater only runs Linux builds on x86_64. Thus, other architectures and platforms are not tested. | |
| Critically, this includes Windows. | |
| - Many crates are not tested. | |
| This could be for a lot of reasons, including that | |
| the crate doesn't compile any more (e.g. used old nightly features), has | |
| broken or flaky tests, requires network access, or other reasons. | |
| - Before Crater can be run, `@bors try` needs to succeed in building artifacts. | |
| This means that if your code doesn't compile, you cannot run Crater. |