🦕 Thanks for your help improving the project! We are so happy to have you!
There are opportunities to contribute to petgraph at any level. It doesn't matter which background you have in either Rust or graph algorithms, we would love to have you and can use your help!
No contribution is too small and all contributions are valued.
There is a discord server where you can ask questions, get help, and chat with other contributors.
This guide will go through the different information you might need to contribute to petgraph. Do not let this guide intimidate you. It should simply be a reference for you, which you can refer to when contributing. The structure of this guide is as follows:
The petgraph project adheres to the Rust Code of Conduct. This describes the minimum behavior expected from all contributors.
We have an entire category of issues which need help. These issues are labeled with P-help-wanted where the P stands for Call for (P)articipation. We further categorize these issues into P-easy, P-medium and P-hard. issues, so that you can find an issue which you feel confident tackling 🦾
Additionally, there is the C-feature-accepted label, which marks feature requests that have been deemed useful and fitting. They are just waiting for someone to implement them! 👀
If you have an idea for a new feature, or if you found a bug, please open a new issue on the GitHub issues page.
Pull Requests are the way concrete changes are made to the code, documentation, and dependencies in petgraph.
Even tiny pull requests (e.g., one character pull request fixing a typo in API documentation) are greatly appreciated. Before making a large change, it is usually a good idea to first open an issue describing the change to get feedback and guidance. This will increase the likelihood of the PR getting merged.
Pull requests address different kinds of changes to the codebase. We are working on templates for the different kinds of pull requests, which will explain teh requirements for each kind of pull request.
Until then, the different kinds of pull requests are described in the old section below.
Reviewing pull requests is a great way to help out the project. When doing so, please keep in mind the following:
Regarding the content of the pull request:
benches directory, and should be run with cargo bench.petgraph does not have any special setup requirements, other than having a working Rust toolchain. The project is built using Cargo.
For running the benchmarks, as well as miri, you will need to switch to the nightly toolchain. You can do this by running:
rustup default nightly
Which will install the nightly toolchain if it is not already installed, and set it as the default toolchain. You can switch back to the stable toolchain by running:
rustup default stable
We use just as a command runner to simplify the commands you need to run. You can install it using cargo:
cargo install just
To understand which commands are available, and what they do, you can run:
just
or have a look at the justfile.
To run a basic test suite, as it is run in CI (using the stable toolchain), you can run:
just ci
Which will run the (cargo) tests and lints. More detailed commands will be explained in the following sections.
Building petgraph is as simple as running:
just build
Testing petgraph is similarly simple:
just test
In CI, we run the tests on different rust versions and toolchains, including nightly, as well as our current minimum supported Rust version (MSRV). You can see which versions are tested exactly in .github/workflows/ci.yml.
Similarly, we also run cargo miri in CI, which is a tool for detecting undefined behavior in Rust code. This will however again require the nightly toolchain:
just miri
This might, however, take a long time to run, so consider running miri-fast instead, which uses nextest, a faster test runner, and skips some tests which take very long:
just miri-fast
Nextest can again be installed using cargo:
cargo install cargo-nextest --locked
We use clippy and rustfmt to ensure that the code is formatted and linted correctly. You can run all linting at once by running:
just lint
Or individually, by running:
just fmt
and
just clippy
Benchmarks can be run by running:
cargo bench
Currently, the petgraph crate is being maintained by:
@ABorgna@starovoid@XVilka@RaoulLuque@indietypHowever, much of the initial development of petgraph was done by:
@blussWe always need more people helping maintain the project, so if you are interested in helping out on a more long-term basis, feel free to introduce yourself on discord or start a discussion.
The following section is just here for historical reasons, until the information on the different kinds of pull requests is included in the different pull request templates.
All pull requests are reviewed by a team member before merging.
Additionally, different kinds of pull requests have different requirements.
We love getting bug fixes!
Make sure to include a regression test, so that we can be sure that we never accidentally re-introduce the bug again.
You made an algorithm faster? Awesome.
When submitting performance improvement, include the following:
A new #[bench] function that exercises this code path, if one doesn't already exist
Before and after cargo bench scores, optionally formatted using cargo-benchcmp
Implementing new graph algorithms is encouraged!
If you're going to implement a new algorithm, make sure that you do the following:
Add a quickcheck property test for the new algorithm
Add a benchmark test for measuring performance of the new algorithm
Document what the algorithm does and in what situations it should be used
Document the big-O running time of the algorithm
Include links to relevant reading materials, such as a paper or Wikipedia
Make the algorithm work with generic graphs, constraining the generic graph type parameter with our existing graph traits, like Visitable, or with new graph traits
Anyone can review a pull request implementing a new algorithm, but the final decision whether or not the algorithm is appropriate for inclusion in the petgraph crate is left to team members.
Additionally, assuming that the new algorithm is merged into petgraph, you are strongly encouraged to join the petgraph team! You are the best person to review any future bug fixes, performance improvements, and whatever other changes that affect this new algorithm.