Contributing

Thank you for wanting to contribute to nmrs!

Guidelines

I'm fairly accepting to all PRs, only with a couple caveats:

Do not submit low-effort or autogenerated code. If you absolutely must, please disclose how you used AI otherwise I will close the PR.
Please try to (when possible) contribute to an issue. This is not a hard ask, I'll still consider your contribution if it makes sense.

Requirements

To run or develop nmrs you need:

Rust (stable) via rustup
A running NetworkManager instance

I also provide a Dockerfile you can build if you don't use Linux and use MacOS instead.

To run tests:

docker compose run test

To run an interactive shell:

docker compose run shell

It goes without saying that this image only works with nmrs. nmrs-gui requires GTK deps which in that case, you are better off just running a VM or learning how to use Linux on a machine instead.

If you decide to run the shell, ensure you run all commands from within the nmrs directory, not root.

cargo test -p nmrs           # run library tests
cargo build -p nmrs          # build the library
cargo check                  # you get the point...

To develop nmrs-gui, you'll need:

GTK4 and libadwaita development libraries
A Wayland compositor

When your branch falls behind `master`

If the respective branch for a PR goes out of sync, I prefer you rebase. I've exposed this setting for you to automatically do so as a contributor on any PR you open.

Issues and Commit Message Hygiene

When you've made changes and are ready to commit, I prefer that you follow the standards explained at Conventional Commits.

I additionally request that you format your commits as such:
type((some issue number)): changes made

For example:

fix(#24): fixed bug where something was happening

Obviously, if there is no issue number to attach, no need to add anything there.

Lastly, please ensure you make atomic commits.

All issues are acceptable. If a situation arises where a request or concern is not valid, I will respond directly to the issue.

Tests

All tests must pass before a merge takes place.

Ensure NetworkManager is running

sudo systemctl start NetworkManager

Test everything (unit + integration)

cargo test --all-features

Integration tests

These require WiFi hardware. Please make sure you run this locally before your PR to ensure everything works.

cargo test --test integration_test --all-features

If you do not have access to WiFi hardware (for whatever odd reason that is), you can do something like this:

sudo modprobe mac80211_hwsim radios=2
cargo test --test integration_test --all-features
sudo modprobe -r mac80211_hwsim

Note: This method only works on Linux

Documentation

When adding new features or changing existing APIs:

Update rustdoc comments in the source code
Add or update examples in the examples/ directory
Update this mdBook documentation if user-facing changes are made
Update the CHANGELOG.md

To build the documentation locally:

# API documentation
cargo doc --open --no-deps

# User guide (this book)
cd docs
mdbook build
mdbook serve --open

Code Style

Follow standard Rust formatting: cargo fmt
Pass clippy checks: cargo clippy -- -D warnings
No unsafe code (enforced by workspace lints)
Add doc comments for public APIs
Write tests for new functionality

License

All contributions fall under the dual MIT/Apache-2.0 license.

Getting Help

Join our Discord server
Open an issue for questions or bugs
Check existing issues and PRs for similar work

nmrs Documentation