2017-02-25 22:42:31 +00:00
|
|
|
# Contributing to the Rust Cookbook
|
|
|
|
|
|
|
|
|
|
Have something useful to add to the Rust Cookbook? We'd love to have it!
|
|
|
|
|
|
|
|
|
|
This document contains information and guidelines that you should read before
|
|
|
|
|
contributing to the project. If you think something in this document should change,
|
|
|
|
|
feel free propose a change in a pull request.
|
|
|
|
|
|
|
|
|
|
## Table of Contents
|
|
|
|
|
* [Getting Started](#getting-started)
|
|
|
|
|
* [How to Contribute](#how-to-contribute)
|
|
|
|
|
* [Crates](#crates)
|
|
|
|
|
* [Tests](#tests)
|
|
|
|
|
* [Style](#style)
|
|
|
|
|
* [Git Commit Messages](#git-commit-messages)
|
|
|
|
|
* [Snippet Style](#snippet-style)
|
|
|
|
|
|
|
|
|
|
## Getting Started
|
|
|
|
|
TODO: Mention Trello and how to join (if we keep using it)
|
|
|
|
|
|
|
|
|
|
## How to Contribute
|
|
|
|
|
TODO: Reporting bugs
|
|
|
|
|
TODO: Project page suggestions
|
|
|
|
|
TODO: Fixing bugs
|
|
|
|
|
TODO: Pull requests
|
|
|
|
|
|
|
|
|
|
## Crates
|
2017-04-30 02:51:16 +00:00
|
|
|
|
|
|
|
|
All crates used by the cookbook are listed in Cargo.toml. If you are
|
|
|
|
|
adding a new crate, first add it there.
|
2017-02-25 22:42:31 +00:00
|
|
|
|
|
|
|
|
## Tests
|
2017-04-30 02:51:16 +00:00
|
|
|
|
|
|
|
|
All examples are tested using [`skeptic`]. Run them with `cargo test`.
|
|
|
|
|
|
|
|
|
|
[`skeptic`]: https://github.com/brson/rust-skeptic
|
2017-02-25 22:42:31 +00:00
|
|
|
|
|
|
|
|
## Style
|
2017-02-25 22:56:49 +00:00
|
|
|
|
2017-02-25 22:42:31 +00:00
|
|
|
### Git Commit Messages
|
|
|
|
|
https://chris.beams.io/posts/git-commit/
|
|
|
|
|
TODO: Possibly take relevant parts from this post or write our own
|
|
|
|
|
|
|
|
|
|
### Snippet Style
|
2017-04-30 02:51:16 +00:00
|
|
|
|
|
|
|
|
Snippets are intended to be read by complete beginners, and copied
|
|
|
|
|
into projects for experimentation. They should follow best practices.
|
|
|
|
|
|
|
|
|
|
Snippets should have a simple single-sentence description
|
|
|
|
|
that describes something a typical Rust user typically wants to do.
|
|
|
|
|
|
|
|
|
|
The snippet should have minimal code that doesn't directly support the
|
|
|
|
|
description of the snippet. Keep extra functions and types to a
|
|
|
|
|
minimum.
|
|
|
|
|
|
|
|
|
|
Follow the template in [src/error_handling_note.md]. Examples always
|
|
|
|
|
set up error handling correctly and propagate errors with `?` (not
|
|
|
|
|
`try!`).
|
|
|
|
|
|
|
|
|
|
Don't use glob imports, even for preludes.
|
|
|
|
|
|
|
|
|
|
Sort imports.
|
|
|
|
|
|
2017-04-30 06:24:42 +00:00
|
|
|
Examples should be simple and obvious enough that an experienced dev
|
|
|
|
|
won't need comments. Explanation should be in prose.
|
|
|
|
|
|
2017-04-30 02:51:16 +00:00
|
|
|
Describe the code in prose, not in comments. Things that should be
|
|
|
|
|
described include any traits imported and their methods used. Think
|
|
|
|
|
about what information here supports the use case and might not be
|
|
|
|
|
obvious to someone new. Say the minimum possible about aspects that
|
|
|
|
|
don't directly support the use case. See [basics.md] for examples.
|
|
|
|
|
|
|
|
|
|
Hyperlink all references to APIs, and style them as `code`.
|
|
|
|
|
|
