Skip to content

Latest commit

 

History

History
78 lines (52 loc) · 2.96 KB

CONTRIBUTING.md

File metadata and controls

78 lines (52 loc) · 2.96 KB
Raw

How to contribute

Ask for help, propose a feature request a feature or report a bug

Feel free to create an issue or open a discussion

Choose an issue to work on

You don't need to find an open issue to contribute a PR. But it is better to make sure the change is actually desirable.

I assign myself to issues when I am working on them. So you can safely pick any unassigned issue.

You may (but don't have to) write a message in the issue to say you are working on it.

Build from source

Run the tests

cargo test --all-features

Check code style

cargo fmt
cargo clippy --all-targets --all-features

Build (and open) documentation

cargo doc --no-deps --all-features --open

Coding standards

Tests

This is a test-driven project. Every new feature and bug fixes must come with tests. If you need help to test your feature or fix, you can ask in a draft PR, and I'll do my best to help you.

API stability

Add stable API

When writting new code make sure you don't expose any unecessary technical detail:

  • Never expose struct fields!
  • Use #[non_exhaustive] for enums and unit structs
  • Be very carefull with public enums. In doubt keep them private.
  • Don't expose types and functions that do no need to be public
  • Don't eagerly implement traits that are not yet needed or related to the use-case
    • except for Debug, Clone, Eq, PartialEq and Default that may be implemented eagerly when it makes sense
    • note that if a new() constuctor does not make sense, Default should not be implemented
    • in case of doubt, don't implement what you don't need, don't worry we can add it later
  • Avoid promissing too much in return types. (e.g. &[T] are better that &Vec<T>)

New API may be gated behind a unstable- cargo flag until it is stabilized.

Do not break existing API

Do not break public API. (See https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md to understand what constitute a breaking change)

Instead create a new API. Eventually we may deprecate the old one and hide it from the doc.

The API may eventually be broken (in a new major version). But I want to avoid that for as long as possible (forever would be perfect). I see a breaking change as good only if it makes future breaking changes less likely to be needed. For example, to make struct field privates is a an acceptable breaking change.

If you don't see how to improve an API without breaking it, you can start a discussion in the issues.

Open a pull request

Don't be afraid of small steps. I'd rather review 5 tiny pull-requests than 1 big.

But to be merged a pull-request needs to be in state ready for release:

  • New features and Bug fixes must comes with automated tests
  • The build must pass
  • The documentation must be up-to-date