Skip to content
This repository was archived by the owner on Sep 30, 2020. It is now read-only.

Commit aa27ab8

Browse files
brsonbrson
committed
Various changes to contributions.html
1 parent 9517376 commit aa27ab8

File tree

1 file changed

+117
-97
lines changed

1 file changed

+117
-97
lines changed

‎contributions.md

Lines changed: 117 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -8,108 +8,65 @@ title: How To Contribute
88
If you're learning Rust, you've no doubt been amazed at how awesome
99
the language is and will be keen to write more Rust code. Hopefully,
1010
you'll also want to make a meaningful contribution to the community.
11-
If you're not sure how best to do that, then hopefully this page will
12-
help. Most of this page is filled with links to lists of issues to
13-
help you find something to work on. There are issues on the Rust
14-
project itself, a number of supporting projects, and some projects
15-
which are large users of Rust.
16-
17-
Writing code isn't the only way to make a meaningful contribution.
18-
Writing tests and documentation is how many people get started and is
19-
really useful. There are links to these kind of issues too. Likewise
20-
finding bugs and filing issues in any of the projects linked here is
21-
very much appreciated. As a reminder, all contributors are expected to
11+
If you're not sure how best to do that, then this page will
12+
help.
13+
14+
**Just want to report a bug in Rust?** [Follow the Rust bug reporting
15+
guide][bugs]. Thanks in advance!
16+
17+
[bugs]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports
18+
19+
Rust is an expansive system of projects, some officially maintained
20+
within the [rust-lang] organization on GitHub, but with many
21+
increasingly-important efforts driven from without by its enthusiastic
22+
community. Newcomers will be interested in [an overview of the
23+
organization, processes, and policies of The Rust Project][dev_proc]
24+
and the project's [CONTRIBUTING.md] file, which explains the specifics
25+
of contributing to [rust-lang/rust].
26+
27+
There are many ways to contribute to the success of Rust: filing,
28+
triaging and fixing bugs; writing documentation and tests; partipating
29+
in the the design of the language and standard libraries through the
30+
RFC process; improving compile-time and run-time performance;
31+
spreading the tendrils of the Rust community ever-outward.
32+
33+
This guide focuses on a few avenues for the new contributor:
34+
35+
* [Bugs, triage, and maintenance](#bugs). Finding issues to fix,
36+
triaging, adding test cases.
37+
* [Documentation](#doc). Not just official documentation, but also
38+
for crates, blog posts, and other unofficial sources.
39+
* [Community building](#comm). Expanding the reach of Rust, and
40+
maintaining its excellence.
41+
* [Tooling, IDEs, and infrastructure](#tool). The hard work of making
42+
Rust accessible to programmers of all kinds.
43+
* [Language and compiler](#comp). Language design, feature
44+
implementation, performance improvement.
45+
* [Libraries](#lib). Including the standard library, but also the
46+
equally-important unofficial crates that make Rust usable.
47+
48+
As a reminder, all contributors are expected to
2249
follow our [Code of Conduct][coc].
2350

51+
[dev_proc]: dev_process.html
52+
[rust-lang]: https://github.com/rust-lang
53+
[rust-lang/rust]: https://github.com/rust-lang/rust
54+
[CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
2455
[coc]: https://www.rust-lang.org/conduct.html
2556

26-
## Getting Started By Scanning Through Issues
27-
28-
One way to get started is to scan through [issues][rust_issues] on
29-
the Rust repo. To start with, look for the [E-easy][e_easy_issues] or
30-
[E-mentor][e_mentor_issues] labels.
31-
32-
- **Yellow A-prefixed** labels state which area of the project an
33-
issue relates to.
34-
- **Magenta B-prefixed** labels identify bugs which belong elsewhere.
35-
- **Green E-prefixed** labels explain the level of experience
36-
necessary to fix the issue.
37-
- **Red I-prefixed** labels indicate the importance of the issue. The
38-
I-nominated label indicates that an issue has been nominated for
39-
prioritizing at the next triage meeting.
40-
- **Orange P-prefixed** labels indicate a bug's priority. These labels
41-
are only assigned during triage meetings, and replace the
42-
I-nominated label.
43-
- **Blue T-prefixed** bugs denote which team the issue belongs to.
44-
- **Dark blue beta-** labels track changes which need to be backported
45-
into the beta branches.
46-
- **Purple** metabug labels mark lists of bugs collected by other
47-
categories.
48-
49-
Contributors with sufficient permissions on the Rust repo can help by
50-
adding labels to triage issues.
51-
52-
[rust_issues]: https://github.com/rust-lang/rust/issues
53-
[e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
54-
[e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
55-
56-
## Getting Started by Topic
57-
58-
#### The Rust compiler
59-
60-
The compiler is part of the [main repo][main_repo], which also
61-
includes the standard library crates and a whole bunch of supporting
62-
code. For questions about the compiler, there is the
63-
[#rustc][rustc_irc] IRC channel. Compiler errors (ICE for 'internal
64-
compiler errors') can be searched for in issues using the
65-
[I-ICE][i_ice_issues] label. These are usually good bugs to start with
66-
because it's easy to know when you've fixed them, and they're often
67-
relatively self-contained. If you're interested in parsing, macros,
68-
syntactic stuff, the [parsing][parsing_issues] label and the
69-
[macro][macro_issues] label are a good places to start.
70-
71-
[main_repo]: https://github.com/rust-lang
72-
[rust_irc]: irc://moznet/rustc
73-
[i_ice_issues]: https://github.com/rust-lang/rust/labels/I-ICE
74-
[parsing_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser
75-
[macro_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser+label%3AA-macros
76-
77-
#### Standard Libraries
78-
79-
[Libstd][libstd], [libcollections][libcollections],
80-
[liballoc][liballoc] and [libcore][libcore] are the main library
81-
crates. These all appear to users as if they are part of libstd, the
82-
standard library. These tend to be very fundamental libraries -
83-
built-in types, low level IO and concurrency, allocation, essential
84-
collections, and so forth. You should join [#rust-libs][libs_irc] if
85-
you are interested in contributing to the Rust libraries.
86-
87-
[libstd]: https://github.com/rust-lang/rust/tree/master/src/libstd
88-
[libcollections]: https://github.com/rust-lang/rust/tree/master/src/libcollections
89-
[liballoc]: https://github.com/rust-lang/rust/tree/master/src/liballoc
90-
[libcore]: https://github.com/rust-lang/rust/tree/master/src/libcore
91-
[libs_irc]: irc://moznet/rust-libs
92-
93-
#### Cargo
94-
95-
[Cargo][cargo_issues] is Rust's package manager.
96-
97-
[cargo_issues]: https://github.com/rust-lang/cargo/issues
98-
99-
#### Tests
57+
<a name="bugs"></a>
58+
## Bugs, triage, and maintenance
10059

101-
Contributing tests is extremely valuable to the Rust project. For the
102-
compiler and standard libraries, there are unit tests (usually)
103-
embedded in the source code and regression tests in the
104-
[src/tests][tests] directory. There is a list of issues which have
105-
(probably) been fixed, but still need a test. Nearly any other project
106-
will be extremely welcoming of new tests too. Writing test cases is a
107-
great way to begin to understand a new project and get started
108-
contributing.
60+
The day-to-day maintenance of the project revolves around Rust's
61+
[issue tracker] and [pull requests], and more help is always
62+
needed.
10963

110-
[test]: https://github.com/rust-lang/rust/tree/master/src/test
64+
The most basic way to get started contributing to Rust is to look for
65+
the [E-easy][e_easy_issues] or [E-mentor][e_mentor_issues]
66+
labels. These are meant to be approachable for new Rust programmers.
11167

112-
#### Checking Older Bugs
68+
Rust is always in need of people to [triage] issues: reproduce bugs,
69+
minimize test cases, apply labels.
11370

11471
Sometimes, an issue will stay open, even though the bug has been
11572
fixed. And sometimes, the original bug may go stale because something
@@ -119,9 +76,30 @@ issue, double check that it's still true, and leave a comment letting
11976
us know if it is or is not. The [least recently updated][lru_issues]
12077
sort is good for finding issues like this.
12178

79+
While Rust has an [extensive test suite][test] there is always more to
80+
test. The [E-needstest] label indicates issues that are thought to be
81+
fixed but don't have tests. Writing test cases is a great way to begin
82+
to understand a new project and get started contributing. For those
83+
especially interested in testing, there are usually *entirely new
84+
classes* of tests that need to be implemented, and asking #rust-internals
85+
what needs to be tested can be fruitful.
86+
87+
Once you've found your way around the project and have created a few
88+
pull requests in a particular area of the project, consider actively
89+
reviewing others' pull requests: reviewership is a rare skill and good
90+
reviewers are always appreciated.
91+
12292
[lru_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
93+
[issue tracker]: https://github.com/rust-lang/rust/issues
94+
[pull requests]: https://github.com/rust-lang/rust/pulls
95+
[e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
96+
[e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
97+
[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage
98+
[E-needstest]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-needstest
99+
[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
123100

124-
#### Documentation
101+
<a name="doc"></a>
102+
## Documentation
125103

126104
Documentation is never good enough and there's never enough of it.
127105
Writing docs is a really valuable way to contribute to open source
@@ -140,7 +118,12 @@ at experienced C++ programmers coming to Rust.
140118
[rust_by_example_issues]: https://github.com/rust-lang/rust-by-example/issues
141119
[rust_for_cpp_issues]: https://github.com/nrc/r4cppp/issues
142120

143-
#### Tools
121+
122+
<a name="comm"></a>
123+
## Community building
124+
125+
<a name="tool"></a>
126+
## Tooling, IDEs, and infrastructure
144127

145128
Tools play a huge part in the success of a language. Rust has some
146129
great tool support, in particular with debugging and package
@@ -155,6 +138,43 @@ management, but we need much more.
155138
multiple installations of the Rust toolchain.
156139
- [homu](https://github.com/barosl/homu/issues) Acts as a gatekeeper for commits.
157140

141+
<a name="libs"></a>
142+
## Libraries
143+
144+
[Libstd][libstd], [libcollections][libcollections],
145+
[liballoc][liballoc] and [libcore][libcore] are the main library
146+
crates. These all appear to users as if they are part of libstd, the
147+
standard library. These tend to be very fundamental libraries -
148+
built-in types, low level IO and concurrency, allocation, essential
149+
collections, and so forth. You should join [#rust-libs][libs_irc] if
150+
you are interested in contributing to the Rust libraries.
151+
152+
[libstd]: https://github.com/rust-lang/rust/tree/master/src/libstd
153+
[libcollections]: https://github.com/rust-lang/rust/tree/master/src/libcollections
154+
[liballoc]: https://github.com/rust-lang/rust/tree/master/src/liballoc
155+
[libcore]: https://github.com/rust-lang/rust/tree/master/src/libcore
156+
[libs_irc]: irc://moznet/rust-libs
157+
158+
<a name="comp"></a>
159+
## Language and compiler
160+
161+
The compiler is part of the [main repo][main_repo], which also
162+
includes the standard library crates and a whole bunch of supporting
163+
code. For questions about the compiler, there is the
164+
[#rustc][rustc_irc] IRC channel. Compiler errors (ICE for 'internal
165+
compiler errors') can be searched for in issues using the
166+
[I-ICE][i_ice_issues] label. These are usually good bugs to start with
167+
because it's easy to know when you've fixed them, and they're often
168+
relatively self-contained. If you're interested in parsing, macros,
169+
syntactic stuff, the [parsing][parsing_issues] label and the
170+
[macro][macro_issues] label are a good places to start.
171+
172+
[main_repo]: https://github.com/rust-lang
173+
[rust_irc]: irc://moznet/rustc
174+
[i_ice_issues]: https://github.com/rust-lang/rust/labels/I-ICE
175+
[parsing_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser
176+
[macro_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser+label%3AA-macros
177+
158178
#### Other Contributions
159179

160180
Try [Github Trending][trending] for currently active Rust projects.

0 commit comments

Comments
 (0)