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.
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:
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:
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
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:
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:
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:
# 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
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).
# Benchmarks (requires nightly) cargo bench # Some benchmarks have a faster path with i128_support cargo bench --features=nightly