Skip to content

Latest commit

 

History

History
64 lines (46 loc) · 3.36 KB

CONTRIBUTING.md

File metadata and controls

64 lines (46 loc) · 3.36 KB
Raw

Contributions are welcome.

tl;dr: Open issues. PR early, PR small. Tests are good. Callback lifetimes are hard.

Contribution guidelines

General RIOT contribution guidelines apply, with some

  • focus points:

    • When wrapping a new RIOT feature, keep it small. Attempting to implement all features of a particular RIOT subsystem easily gets caught in long iterations of review. Try wrapping a minimal viable version first, and let's take it from there.

    • Let's verify concepts early. Opening an issue before larger changes, creating them as draft PRs or discussing it on our Matrix channel are all convenient ways to do that.

    • New features should come with tests, at least on a coarse granularity. Tests in ./tests/ are automatically picked up by CI.

  • and alterations:

    • RIOT has no coding conventions for Rust; instead, common Rust conventions apply. Public items should be documented, and code should be cargo fmt before each commit.

    • Merging criteria are not as strict as in RIOT OS: RIOT maintainers may merge PRs without a 2nd pair of eyes (but are encouraged to solicit review on larger changes).

      Before code from this crate gets used by RIOT OS, it undergoes a secondary review step similar to PR #20786, just like any external package code.

    • The license of this crate is "MIT OR Apache-2.0" as stated in Cargo.toml and the README. This eases interoperability with the rest of the Rust ecosystem; beware that built binaries include RIOT OS, and thus have LGPL-2.1 components.

Common pitfalls

  • Threads and interrupts in RIOT are modelled as is common in Rust: Data needs to be Send to be passed around. Whenever generic data (in particular references) is passed into C functions, trait bounds need to ensure that it is Send.

  • Registering callbacks with RIOT OS typically means that the OS may invoke the callback at any time. Thus the callback either must be 'static, or it needs to be ensured that the callback is fully unregistered before its lifetime ends.

    Note that we can not rely on Drop to be called (for any user may safely forget() an item at any time).

    Running user code in Rust closures is a common workaround (eg. in thread::scope), but beware that any items in that scope need to be branded (like with the 'id of the thread scope): Otherwise, users might create nested scopes and switch around the provided types, delaying their cleanup from the inner to the outer scope.