CONTRIBUTING.md

Contributing

Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in the work, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

Tests

To run the tests, simply run:

cargo test

There are two variants of tests, unit tests and doctests.

The unit tests are added inline as an additional test module:

#[cfg(test)]
mod tests {
    use super::GreatThing;

    #[test]
    fn test_getters() {
        let thing = GreatThing::new(1);
        assert_eq!(thing.number(), 1);
    }
}

Doctests are added to traits and structs to illustrate their usage:

/// A thing to have
///
/// # Examples
/// ```
/// use tdigest::thing::GreatThing;
///
/// let thing = GreatThing::new(1);
/// thing.do_something();
/// ```
struct GreatThing {}

Benchmarks

Apart from the normal tests, please note that also the benchmarks must pass. You can test this (without actually benchmarking) using:

cargo bench --verbose --all -- --test

The benchmarks are implemented using criterion.rs. To benchmark the library, run:

cargo bench

Formatting

Use rustfmt to format the code:

cargo fmt

Clippy / Linting

It would be nice if you could follow clippy loosely and take its recommendation into account, although passing this linter is currently not a hard requirement.

cargo clippy

There are however some lints provided by rustc which needs to be fulfilled:

• anonymous_parameters
• bare_trait_objects
• const_err
• dead_code
• illegal_floating_point_literal_pattern
• missing_debug_implementations
• missing_docs
• non_camel_case_types
• non_snake_case
• non_upper_case_globals
• unknown_lints
• unreachable_code
• unreachable_patterns
• unreachable_pub
• unsafe_code
• unused_extern_crates

Documentation

The documentation of data structures uses the following style:

A simple introduction what this data structure can do. Math is represented as code (`x = a + b`).

# Examples
\`\`\`
use pdatastructs::foo::MyStructure;

// set up data structure
let param1 = 0.2;
let param2 = true;
let mut whatever = MyStructure::new(param1, param2);

// add some data
whatever.add(&"my super long string");

// later
assert!(whatever.can_do_something());
\`\`\`

# Applications
- list some theoretical and known real world applications

# How It Works
Explain, how the data structure works.

\`\`\`text
might use some nice ASCII diagrams

+-------++---+---+---+---+---+---+---+---+
| block || 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|  data ||   |   |   |   |   |   |   |   |
+-------++---+---+---+---+---+---+---+---+
\`\`\`

## Insertion
Explain insertion...

## Query
Explain query...

# See Also
- link to data structures that are similar in standard library, this library, 3rd-party libs

# References
- ["Title", Author1, Author2, Year](https://some-open-access.net/foo/bar)
- [Wikipedia: Data Structure](https://en.wikipedia.org/wiki/Data_structure)

Sometimes, you may need some mathematical plots to illustrate certain things. Use gnuplot to create these. First, setup a terminal plotter:

unset key
set term dumb feed 60, 20

Optionally, set the range for the plot:

set xrange [0:1]

Finally, create a plot and copy the output to the markdown documentation:

plot x * x + 10