Add development documentation. (#91)

Author: molpopgen

CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+`tskit_rust` is a free and open-source project that welcomes contributions from everyone.
+The [developer](https://github.com/molpopgen/tskit_rust/blob/main/DEVELOPMENT.md)] and [design](https://github.com/molpopgen/tskit_rust/blob/main/DESIGN.md) guides will help you get started. 
+
+We have an active slack group where tskit and associated projects are discussed.
+If you wish to join email [[email protected]](mailto:[email protected]).
+
+We ask all users to follow our [code of conduct](https://github.com/tskit-dev/.github/blob/main/CODE_OF_CONDUCT.md)
+when interacting with the project.

DESIGN.md

@@ -0,0 +1,15 @@
+# Design
+
+## Including the `tskit` `C` code.
+
+We manually copy the source files from the current stable release.
+We cannot use submodules because the `tskit` repository contains symbolic links, which causes problems with `bindgen`.
+
+## Key principles
+
+* Don't reinvent the wheel.
+  If there is a `C` function in place, call it.
+  Calling existing functions takes advantage of the high test coverage of `tskit`.
+* Prefer rust idioms where possible.
+  For example, provide iterator types instead of manual `next/advance` functions.
+  See how `NodeIterator` works by looking in `src/traits.rs` and `src/trees.ts` for an example of a reusable iterator pattern.

DEVELOPMENT.md

@@ -0,0 +1,121 @@
+# Developer's guide
+
+## Targeted rust version
+
+All development targets `stable`.
+
+## rust tool chain
+
+Install `rust` as described [here](https://www.rust-lang.org/tools/install).
+
+Then, install [rustfmt](https://github.com/rust-lang/rustfmt) and [clippy](https://github.com/rust-lang/rust-clippy), which are required to make sure that changes can pass CI tests (see below):
+
+```sh
+rustup component add rustfmt clippy
+```
+
+### Other useful tools
+
+[tarpaulin](https://docs.rs/crate/cargo-tarpaulin/) for calculating test coverage:
+
+```sh
+cargo install cargo-tarpaulin
+```
+
+
+## Continuous integration (CI)
+
+GitHub actions/work flows handle all CI:
+
+* `rustfmt` checks code formatting
+* `clippy` checks for code "lint".
+* The library is built, and tests are run, against both rust `stable` and `beta`.
+
+### More about clippy
+
+`clippy` is a very opinionated code "linter".
+Any changes must pass all `clippy` checks.
+Some of these checks may seem stylistic, meaning that you are being asked to replace working code with a different implementation.
+In these cases `clippy` is suggesting a more idiomatic approach to do what you are asking.
+We accept `clippy`'s recommendations for two reasons.
+First, it is best to respect language idioms  whenever possible ("don't force rust to act like C or C++").
+Second, these recommendations have been useful in learning more about rust.
+
+## Building the library
+
+```sh
+cargo build
+```
+
+### Building examples
+
+```sh
+cargo build --examples
+```
+
+### Release mode builds
+
+Add `--release` to any of the above.
+This flags adds optimizations and removes debugging symbols.
+
+## Building the documentation
+
+```sh
+cargo doc
+```
+
+Then, point your browser at `target/doc/tskit/index.html`.
+
+## Running tests
+
+To run tests and doc tests:
+
+```sh
+cargo test
+```
+
+To test examples:
+
+```sh
+cargo test --examples
+```
+
+### Test coverage
+
+Using `tarpaulin`:
+
+```sh
+cargo tarpaulin --exclude-files '*.c' --exclude-files '*.h' -o html
+```
+
+We exclude `*.c` and `*.h` because it is `tskit`'s job to manage the coverage of those files.
+
+Some notes on what `tarpaulin` does:
+
+* The coverage includes the test code itself, which is a bit annoying.
+  In the future, we may move all tests to a separate directory and exclude them from the calculation.
+
+## Running optimized examples
+
+The default build is `debug`, which makes the examples slow.
+To run `release` builds of examples:
+
+```sh
+cargo build --release --examples
+```
+
+The binaries will be in `target/release/examples/`.
+
+## Tips and tricks
+
+### Cleaning up the various builds
+
+```sh
+cargo clean
+```
+
+### Cleaning out the dependency database
+
+```sh
+rm -f Cargo.lock
+```