If you have come here to learn how to contribute to mdBook, we have some tips for you!
First of all, don't hesitate to ask questions!
Use the issue tracker, no question is too simple.
If we don't respond in a couple of days, ping us @Michael-F-Bryan, @budziq, @steveklabnik, @frewsxcv it might just be that we forgot.
Issues to work on
Any issue is up for the grabbing, but if you are starting out, you might be interested in the E-Easy issues. Those are issues that are considered more straightforward for beginners to Rust or the codebase itself. These issues can be a good launching pad for more involved issues. Easy tasks for a first time contribution include documentation improvements, new tests, examples, updating dependencies, etc.
When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you. Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
Issues on the issue tracker are categorized with the following labels:
- A-prefixed labels state which area of the project an issue relates to.
- E-prefixed labels show an estimate of the experience necessary to fix the issue.
- M-prefixed labels are meta-issues used for questions, discussions, or tracking issues
- S-prefixed labels show the status of the issue
- T-prefixed labels show the type of issue
mdBook builds on stable Rust, if you want to build mdBook from source, here are the steps to follow:
Navigate to the directory of your choice
Clone this repository with git.
git clone https://github.com/rust-lang/mdBook.git
Navigate into the newly created
The resulting binary can be found in
mdBook/target/debug/ under the name
We love code quality and Rust has some excellent tools to assist you with contributions.
Formatting Code with rustfmt
Before you make your Pull Request to the project, please run it through the
This will ensure we have good quality source code that is better for us all to maintain.
rustfmt has a lot more information on the project. The quick guide is
- Install it
rustup component add rustfmt
- You can now run
rustfmton a single file simply by...
... or you can format the entire project with
When run through
cargoit will format all bin and lib files in the current crate.
For more information, such as running it from your favourite editor, please see the
rustfmt project. rustfmt
Finding Issues with Clippy
Clippy is a code analyser/linter detecting mistakes, and therfore helps to improve your code.
Like formatting your code with
rustfmt, running clippy regularly and before your Pull Request will
help us maintain awesome code.
The best documentation can be found over at rust-clippy
- To install
rustup component add clippy
- Running clippy
Clippy has an ever growing list of checks, that are managed in lint files.
Making a pull-request
When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub. One of the core maintainers will then approve the changes or request some changes before it gets merged.
That's it, happy contributions!