1Contributing to ``petgraph``
2============================
3
4Hi! We'd love to have your contributions! If you want help or mentorship, reach
5out to us in a GitHub issue, or ping ``bluss`` in `#rust on irc.mozilla.org`_
6and introduce yourself.
7
8.. _`\#rust on irc.mozilla.org`: irc://irc.mozilla.org#rust
9
10* `Building`_
11
12* `Testing`_
13
14* `Pull Requests`_
15
16  * `Bug Fixes`_
17
18  * `Performance Improvements`_
19
20  * `Implementing New Algorithms`_
21
22* `Where We Need Help`_
23
24* `Team`_
25
26Building
27--------
28
29::
30
31    $ cargo build
32
33Testing
34-------
35
36::
37
38    $ cargo test --features all
39
40Pull Requests
41-------------
42
43All pull requests are reviewed by a team_ member before merging.
44
45Additionally, different kinds of pull requests have different requirements.
46
47Bug Fixes
48.........
49
50We love getting bug fixes!
51
52Make sure to include a regression test, so that we can be sure that we never
53accidentally re-introduce the bug again.
54
55Performance Improvements
56........................
57
58You made an algorithm faster? Awesome.
59
60When submitting performance improvement, include the following:
61
62* A new ``#[bench]`` function that exercises this code path, if one doesn't
63  already exist
64
65* Before and after ``cargo bench`` scores, optionally formatted using
66  `cargo-benchcmp`_
67
68.. _`cargo-benchcmp`: https://github.com/BurntSushi/cargo-benchcmp
69
70Implementing New Algorithms
71...........................
72
73Implementing new graph algorithms is encouraged!
74
75If you're going to implement a new algorithm, make sure that you do the
76following:
77
78* Add a ``quickcheck`` property test for the new algorithm
79
80* Add a ``benchmark`` test for measuring performance of the new algorithm
81
82* Document what the algorithm does and in what situations it should be used
83
84* Document the big-O running time of the algorithm
85
86* Include links to relevant reading materials, such as a paper or Wikipedia
87
88* Make the algorithm work with generic graphs, constraining the generic graph
89  type parameter with our existing graph traits, like ``Visitable``, or with new
90  graph traits
91
92Any team_ member can review a pull request implementing a new algorithm, but the
93final decision whether or not the algorithm is appropriate for inclusion in the
94``petgraph`` crate is left to ``@bluss``.
95
96Additionally, assuming that the new algorithm is merged into ``petgraph``, you
97are *strongly* encouraged to join the ``petgraph`` team_! *You* are the best
98person to review any future bug fixes, performance improvements, and whatever
99other changes that affect this new algorithm.
100
101Where We Need Help
102------------------
103
104* Issues labeled `"help wanted"`_ are issues where we could use a little help
105  from you.
106
107* Issues Labeled `"mentored"`_ are issues that don't really involve any more
108  investigation, just implementation. We've outlined what needs to be done, and
109  a team_ member has volunteered to help whoever claims the issue implement it,
110  and get the implementation merged.
111
112.. _`"help wanted"`:
113   https://github.com/bluss/petgraph/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
114
115.. _`"mentored"`:
116   https://github.com/bluss/petgraph/issues?q=is%3Aopen+is%3Aissue+label%3A%22mentored%22
117
118Team
119----
120
121The ``petgraph`` team consists of:
122
123* ``@bluss``
124* ``@fitzgen``
125
126We need more team members to help spread out reviewing and maintenance
127responsibilities — want to join us? `Drop a comment in this issue!`_
128
129.. _`Drop a comment in this issue!`: https://github.com/bluss/petgraph/issues/TODO
130