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)

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 examples/wasm-demo directory and follow the instruction in the README.md file under that directory.

Is my code meets the styling guideline

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 }

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