1Thanks for contributing to `Plotters`! 2 3Here's the useful information about contributing to Plotters. 4 5# License 6 7The `Plotters` project is under MIT license. 8You may interested in reading [the full text of the license](https://github.com/38/plotters/blob/master/LICENSE). 9If you have any questions or concerns please contact us at <haohou302@gmail.com>. 10 11# Contributing to Plotters codebase 12 13You are warmly welcomed to contribute code and make Plotters better. Here's a few things that may be helpful to you. 14 15## How to make sure my code works 16 17*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. 18 19Before you finalize your PR, please check the following thing: 20 21- 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](#testing-notes). 22 23- Please run the benchmark to check if the performance changed compare to the master branch. 24 25- 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) 26 27 ```bash 28 cargo test --doc 29 cargo build --release --examples 30 for i in examples/*.rs 31 do 32 ./target/release/examples/$(basename $i .rs) 33 done 34 cd plotters-doc-data 35 git status 36 ``` 37 38- 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](https://github.com/38/plotters/blob/master/examples/wasm-demo) directory and follow the instruction in the `README.md` file under that directory. 39 40## Is my code meets the styling guideline 41 42Although there's no strictly enforced rules for the style, but please read the following recommendations before you start work. 43 44- 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) 45- For naming, acronyms or initials aren't normally used in the code base. Descriptive identifier is highly recommended. 46- Documentation is highly recommended. (But there are still a lot of undocumented code unfortunately). 47- For API documentation, we normally follows Doxygen's style, which looks like 48 49```rust 50/// Some description to this API 51/// - `param_1`: What param_1 do 52/// - `param_2`: What param_2 do 53/// - **returns**: The return value description 54fn foo(param_1: u32, param_2: u32) -> u32{ 0 } 55``` 56 57## Top Level Documentation and Readme 58 59Please notice we put almost same content for top level `rustdoc` and `README.md`. Thus the both part are generated by script. 60If you need to modify the readme and documentation, please change the template at [doc-template/readme.template.md](https://github.com/38/plotters/blob/master/doc-template/readme.template.md) and 61use the following command to synchronize the doc to both `src/lib.rs` and `README.md`. 62 63```bash 64bash doc-template/update-readme.sh 65``` 66 67## Testing Notes 68 69As 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. 70 71### Native 72 73Testing all features: 74 75```bash 76cargo test --all-features 77``` 78 79Testing no features at all: 80 81```bash 82cargo test --no-default-features --lib 83``` 84 85Since all examples and most doc-test requires `bitmap` features, so we don't test examples and doc test in this case. 86 87### WebAssembly 88 89Wasm target is not tested by default, and you may want to use [wasm-bindgen](https://rustwasm.github.io/docs/wasm-bindgen/wasm-bindgen-test/usage.html) CLI tool. 90 91Installation: 92 93```bash 94rustup target add wasm32-unknown-unknown 95cargo install wasm-bindgen-cli 96``` 97 98Additionally, the web browser and its driver should be available, please see [Configuring Which Browser is Used](https://rustwasm.github.io/wasm-bindgen/wasm-bindgen-test/browsers.html#configuring-which-browser-is-used-1). For example, to use Firefox, its binary (`firefox`) and [geckodriver](https://github.com/mozilla/geckodriver/releases) must be on your `$PATH`. 99 100Usage (only library tests are supported for now): 101 102```bash 103cargo test --lib --target wasm32-unknown-unknown 104``` 105 106For the debugging you could set the `NO_HEADLESS=1` environment variable to run the tests using the local server instead of the headless browser. 107 108### Minimal Supported Compiler Version 109 110Currently we should make sure Plotters is compatible with rustc 1.36.0. 111Before making a PR, please check if the code compile with 1.36.0 (with default features). 112 113### Code Coverage 114 115For for the code coverage information you may want to use [cargo-tarpaulin](https://crates.io/crates/cargo-tarpaulin). Please note that it works with x86_64 GNU/Linux only, and the doc tests coverage require nightly Rust. 116 117Installation ([pycobertura](https://pypi.python.org/pypi/pycobertura) is used to get the detailed report about the coverage): 118 119```bash 120cargo install cargo-tarpaulin 121pip install pycobertura 122``` 123 124Usage: 125 126```bash 127cargo tarpaulin --all-features --run-types Tests Doctests -o Xml --output-dir target/test 128pycobertura show target/test/cobertura.xml 129``` 130 131 132