Be civil. If you need a code of conduct, have a look at Bevy's.
If you have any suggestions for the book, such as ideas for new content, or if you notice anything that is incorrect or misleading, please file issues in the GitHub repository!
See the book's maintenance policy.
If you simply want to contribute code examples to the book, feel free to make a PR. I can take care of writing the book text / page that your code will be displayed on.
The code for cookbook examples should be provided as a full, runnable,
example file, under
src/code/examples. The book page will only show the
relevant parts of the code, without unnecessary boilerplate.
Always use mdbook anchor syntax, not line numbers, to denote the parts of the code to be shown on the page.
If you contribute a cookbook example, I will credit you in the book by your github username with a link to the PR. Please let me know if you prefer not to be credited, or if you would like to be credited in another way (but no commercial self-promotion allowed).
Contributing Book Text
I do not directly merge book text written by other people. This is because I want the book to follow my own editorial style.
If you would like to write new content for the book, feel free to make a PR with the content to be included, but note that it will likely not be preserved exactly as you wrote it.
I will likely merge it into a temporary branch and then edit or rewrite it as I see fit, for publishing into the book.
To avoid complications with copyright and licensing, you agree to provide any contributions you make to the project under the MIT-0 No Attribution License.
Note that this allows your work to be relicensed without preserving your copyright.
As described previously, the actual published content in the book will be my own derivative work based on your contributions. I will license it consistently with the rest of the book; see: License.
Aim for simplicity and minimalism. Do not include things irrelevant to getting the point across.
"Perfection is achieved not when there is nothing more to add, but when there is nothing more to remove."
Don't forget to point out potential gotchas and other relevant practical considerations.
Try to use the most common/standard terminology and keywords, to make things easy to find. Don't come up with new/extra terminology of your own.
Avoid repeating information found elsewhere in the book, prefer linking to it instead.
Avoid long lines of code, to keep it readable on small screens.
Use reasonable formatting that does not deviate much from the common conventions used by the Rust language community. If deviating from those standards allows for the code to be presented better in the context of the book, then doing so is preferable.
Please do not use
rustfmt. Code should be manually formatted for best
presentation in the book.
Make it easy to read.
- Be brief. Try to cover all important information without verbose explanations.
- Prefer simple English with short sentences.
- Avoid information overload:
- Split things into short paragraphs.
- Avoid introducing many (even if related) topics at the same time.
- Cover advanced usage separately from the basics.