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