Merge pull request #443 from pitdicker/contributing

Add CONTRIBUTING.md

Author: pitdicker

CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to Rand
+
+Thank you for your interest in contributing to Rand!
+
+The following is a list of notes and tips for when you want to contribute to
+Rand with a pull request.
+
+If you want to make major changes, it is usually best to open an issue to
+discuss the idea first.
+
+Rand doesn't (yet) use rustfmt. It is best to follow the style of the
+surrounding code, and try to keep an 80 character line limit.
+
+
+## Documentation
+
+We especially welcome documentation PRs.
+
+As of Rust 1.25 there are differences in how stable and nightly render
+documentation links. Make sure it works on stable, then nightly should be good
+too. One Travis CI build checks for dead links using `cargo-deadlinks`. If you
+want to run the check locally:
+```sh
+cargo install cargo-deadlinks
+# It is recommended to remove left-over files from previous compilations
+rm -rf /target/doc
+cargo doc --no-deps
+cargo deadlinks --dir target/doc
+```
+
+When making changes to code examples in the documentation, make sure they build
+with:
+```sh
+cargo test --doc
+```
+
+A helpful command to rebuild documentation automatically on save (only works on
+Linux):
+```
+while inotifywait -r -e close_write src/ rand_core/; do cargo doc; done
+```
+
+
+## Testing
+
+Rand already contains a number of unit tests, but could use more. Also the
+existing ones could use clean-up. Any work on the tests is appreciated.
+
+Not every change or new bit of functionality requires tests, but if you can
+think of a test that adds value, please add it.
+
+Depending on the code you change, test with one of:
+```sh
+cargo test
+cargo test --package rand_core
+# Test log, serde and 128-bit support
+cargo test --features serde1,log,nightly
+```
+
+We want to be able to not only run the unit tests with `std` available, but also
+without. Because `thread_rng()` and `FromEntropy` are not available without the
+`std` feature, you may have to disable a new test with `#[cfg(feature="std")]`.
+In other cases using `::test::rng` with a constant seed is a good option:
+```rust
+let mut rng = ::test::rng(528); // just pick some number
+```
+
+Only the unit tests should work in `no_std` mode, we don't want to complicate
+the doc-tests. Run the tests with:
+```sh
+# Test no_std support
+cargo test --lib --no-default-features
+cargo test --package rand_core --no-default-features
+
+# Test no_std+alloc support; requires nightly
+cargo test --lib --no-default-features --features alloc
+```
+
+
+## Benchmarking
+
+A lot of code in Rand is performance-sensitive, most of it is expected to be
+used in hot loops in some libraries/applications. If you change code in the
+`rngs`, `prngs` or `distributions` modules, especially when you see an 'obvious
+cleanup', make sure the benchmarks do not regress. It is nice to report the
+benchmark results in the PR (or to report nothing's changed).
+
+```sh
+# Benchmarks (requires nightly)
+cargo bench
+# Some benchmarks have a faster path with i128_support
+cargo bench --features=nightly
+```