Skip to content

Latest commit

 

History

History
130 lines (86 loc) · 5.27 KB

CONTRIBUTING.md

File metadata and controls

130 lines (86 loc) · 5.27 KB
Raw

Thanks for contributing to Plotters!

Here's the useful information about contributing to Plotters.

License

The Plotters project is under MIT license. You may interested in reading the full text of the license. If you have any questions or concerns please contact us at haohou302@gmail.com.

Contributing to Plotters codebase

You are warmly welcomed to contribute code and make Plotters better. Here's a few things that may be helpful to you.

How to make sure my code works

Help wanted: You may realize that Plotters doesn't have a high testing coverage, but we are trying hard to improve. It would be nice if you add more test cases for newly added code, or contribute new test cases directly.

Before you finalize your PR, please check the following thing:

  • Please make sure all test case passes. If any case fails, we need to dig into that. For more details about testing, please read the Testing notes.

  • Please run the benchmark to check if the performance changed compare to the master branch.

  • Please run the following command to check if the example output changes. (There shouldn't be any change if you are not modifying the layout)

    cd plotters
cargo test --doc
cargo build --release --examples
for i in examples/*.rs
do
../target/release/examples/$(basename $i .rs)
done
cd plotters-doc-data
git status

  • Please make sure the WASM target works as well. The easiest way to do that is try to run our WASM demo under plotters/examples/wasm-demo directory and follow the instruction in the README.md file under that directory.

Does my code meet the styling guidelines

Although there's no strictly enforced rules for the style, but please read the following recommendations before you start work.

  • In general, the only guide line is we need to make sure cargo fmt doesn't change anything. So it's recommended use cargo fmt to fix the code styling issues before you wrap up the work. (Such as submit a PR)
  • For naming, acronyms or initials aren't normally used in the code base. Descriptive identifier is highly recommended.
  • Documentation is highly recommended. (But there are still a lot of undocumented code unfortunately).
  • For API documentation, we normally follows Doxygen's style, which looks like
/// Some description to this API
/// - `param_1`: What param_1 do
/// - `param_2`: What param_2 do
/// - **returns**: The return value description
fn foo(param_1: u32, param_2: u32) -> u32{ 0 }

Top Level Documentation and Readme

Please notice we put almost same content for top level rustdoc and README.md. Thus the both part are generated by script. If you need to modify the readme and documentation, please change the template at plotters/doc-template/readme.template.md and use the following command to synchronize the doc to both src/lib.rs and README.md.

bash doc-template/update_readme.sh

Testing Notes

As the project is intended to work in various environments, it's important to test its all features and different feature combinations. The notes below may help you with that task.

Native

Testing all features:

cargo test --all-features

Testing no features at all:

cargo test --no-default-features --lib

Since all examples and most doc-test requires bitmap features, so we don't test examples and doc test in this case.

WebAssembly

Wasm target is not tested by default, and you may want to use wasm-bindgen CLI tool.

Installation:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

Additionally, the web browser and its driver should be available, please see Configuring Which Browser is Used. For example, to use Firefox, its binary (firefox) and geckodriver must be on your $PATH.

Usage (only library tests are supported for now):

cargo test --lib --target wasm32-unknown-unknown

For the debugging you could set the NO_HEADLESS=1 environment variable to run the tests using the local server instead of the headless browser.

Minimal Supported Compiler Version

Currently we should make sure Plotters is compatible with rustc 1.36.0. Before making a PR, please check if the code compile with 1.36.0 (with default features).

Code Coverage

For for the code coverage information you may want to use cargo-tarpaulin. Please note that it works with x86_64 GNU/Linux only, and the doc tests coverage require nightly Rust.

Installation (pycobertura is used to get the detailed report about the coverage):

cargo install cargo-tarpaulin
pip install pycobertura

Usage:

cargo tarpaulin --all-features --run-types Tests Doctests -o Xml --output-dir target/test
pycobertura show target/test/cobertura.xml