# Contributing to poolio

Contributions are welcome!
But please read this guide before.

## Code

If you plan to contribute code please take the following subsections into account.

### Implementation

Pay attention to security, usability, maintainability and performance (roughly in that order).
Generally, try to adhere to the coding-style of the current implementation to keep reading the code easy.
Specifically,
- make sure that the code is formatted correctly by running `cargo fmt --all -- --check`.
- make sure that the linter does not complain too much by running `cargo clippy --all --benches --examples --tests --all-features` followed by `-- -W clippy::pedantic` or `-- -W clippy::nursery` if output will be interpreted very carefully.

### Documentation

Document everything adhering to the current style.
In particular, comment private functions.
In the end, make sure that the docs build by running `cargo doc --no-deps --document-private-items`.

### Testing

If you add code then also add tests as necessary.
Both integration- and unit-tests.
It is also suggested to include one documentation-test for each public API function.
In the end, make sure that all tests work as expected by running `cargo test`.

## GitHub

This project is hosted on GitHub.
In the folllowing it is briefly described how this project intends to leverage GitHub for development.

### Issues

GitHub Issues is how contributors shall communicate.
Issue-templates are provided to type communication a bit.
But in doubt, feel free to use blank issues.

### Workflows

When making a contribution keep an eye on the [workflows](.github/workflows).

In a nutshell, what they do is

- Audit
  * checking for known bugs in dependencies
- CI
  * checking if tests run
  * checking for memory leak
  * checking format
  * checking for lints
  * checking documentation

### Pull Requests

As usual, if you can not directly push to the repository use pull requests for contributions.
A pull request-template is provided to assist you.
Otherwise try to keep pull requests small and focused (like a topic-branch - see [Git](#git)).
In any case, take all the other sections into account to ease the pain of merging your pull request.

## Git

This project uses git for version control and contributors are kindly asked to use git as described in the [git-book](https://git-scm.com/book/en/v2).
In the following, the most important aspects are recounted and a few things are nailed down.

### Commits

Commit in 'sensible' units.
In particular, do NOT
- misuse commits for your backup-strategy.
- rewrite your commit history after pushing.

Moreover run `git diff --check` before a commit to check for whitespace errors.

#### Messages

A commit message is written in the imperative (e.g.: 'Fix bug' instead of 'Fixed bug').
The first line of a commit message is a short description of the changeset in less than 50 characters.
Optionally, it can be followed by a blank second line and a more detailed explanatory text starting at the third line.
The text should i.p. motivate the change and explain the difference.

### Branching

This project's branching workflow is 'progressive-stability branching'.
This means that there is a permanent `development`-branch (organizing development) in addition to the `master`-branch.
`development` is merged into master whenever it is in a stable state.
Actual development takes place in so-called topic-branches (e.g. `iss4` to handle the fourth issue) emanating from `development`.
The topic-branches are merged back and deleted when the topic is treated.

## Versioning

This project uses [Semantic Versioning](https://semver.org) - read that if you do not already know it.
When `development` is in a state such that [Semantic Versioning](https://semver.org) requires a version-action then edit the `version`-field of [Cargo.toml](Cargo.toml) accordingly and make a commit with message 'Release version X.Y.Z'.
Check if publishing would work with `cargo publish --dry-run`.
Afterwards tag the commit (`git tag vX.Y.Z -m 'Release version X.Y.Z'`) and merge development back into master.
Finally, make a release on GitHub (do not forget to attach the full benchmark results) and publish on crates.io.