Thank you for your interest in contributing to Crater! This document contains
some information to help you get started. If you have any question please join
the #crater channel on the rust-lang Discord!
- Choosing an issue to work on
- Setting up a local Crater environment
- Setting up a personal craterbot instance
- Submitting your pull request
The issue tracker contains most of the bugs and feature requests: if you want to work on something but you don't exactly know what, you can look for unassigned issues in there. There are some labels you can check:
E-easy: these small issues can be fixed with little effort, and are great to get familiar with the Crater codebaseE-mentor: these issues contain mentoring instructions in the comments, with some hints on how to fix the issueE-needs-help: the Crater developers need help to fix these issues, and they might take a while to be properly fixed
Please remember to comment on an issue when you start working on it, to avoid multiple people working on the same one!
Crater needs the latest Rust stable release to be compiled, and at the moment it only works on Linux systems (help with Windows support is needed). You also need to have Docker installed.
Once you cloned the repository, you can setup the local Crater environment with the following command:
cargo run -- prepare-local
This command will setup the internal Rust toolchain used by Crater, generate the list of crates to test and download the Docker image used to test the crates.
You can check out the CLI Usage documentation to learn how to interact with the Crater CLI.
To setup a personal craterbot instance you need to have a second GitHub account to be used as the bot, and a personal repo you can use for tests (a private one is recommended, but a public one works just fine).
First of all you need to create your local tokens.toml file by copying the
example one, located at tokens.example.toml. Add this line at the bottom (in
the [agents] section):
"token" = "agent-1"
Then you need to setup the GitHub webhook that points to your local instance. If you don't have a domain you can point to your local machine it's recommended to use a tunnel like ngrok. The Crater server will listen on port 8000 by default.
Go to the webhooks settings of the repo you want to use for tests, and setup a
new one that points to https://your.domain/webhooks, accepts JSON requests
and requests the issue_comment events. Also you need to put a secret key of
your choice, and copy it in the webhooks-secret field of tokens.toml.
Then you need to get a personal access token for your bot account. The token
needs access to the repo and read:org scopes, and you can put it in the
api-token field of tokens.toml.
Finally you need to setup an S3-like bucket where Crater will upload the
generated reports. The token.example.toml file already contains credentials
for the Minio playground, which is free to use but frequently
resets itself. If the crater-reports bucket was deleted in a periodic cleanup
you can download the Minio client and recreate the bucket with:
mc mb play/crater-reports
mc policy download play/crater-reports
Now you can start the server and an agent, with the following commands (execute every one in a different terminal window):
cargo run -- server
cargo run -- agent http://127.0.0.1:8000 token
Before submitting your pull request, you need to lint the code in the project, as otherwise the continuous integration builds will fail.
This project makes use of rustfmt and clippy to format the code, and catch common mistakes respectively.
To install rustfmt, you should follow the quick start instructions to install it using the rustup tool.
To install clippy, you should follow the usage instruction to install it using the rustup tool.
To lint the code, run cargo fmt to format your code and cargo clippy to catch common mistakes and improve your code.