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

Commit 1bb607f

Browse files
brsonbrson
committed
Break contribution page into subpages
1 parent c9c8f02 commit 1bb607f

File tree

7 files changed

+441
-401
lines changed

7 files changed

+441
-401
lines changed

‎contribute-bugs.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
layout: default
3+
title: Contributing to Rust — finding, triaging and fixing issues · The Rust Programming Language
4+
---
5+
6+
# Contributing to Rust — finding, triaging and fixing issues
7+
8+
The day-to-day maintenance of the project revolves around Rust's
9+
[issue tracker] and [pull requests][PR], and more help is always
10+
needed. The most basic way to get started contributing to Rust is to
11+
look for the [E-easy] or [E-mentor] labels. These are meant to be
12+
approachable for new Rust programmers.
13+
14+
On `E-mentor` issues an experienced Rust developer has volunteered in
15+
the comments to mentor you through solving the issue and [submitting
16+
the fix via GitHub pull request][pull]. Contact them about the issue,
17+
on the issue tracker by [@mentioning] their name in a comment, on IRC,
18+
or through email. Note that Rust developers get a lot of notifications
19+
and it is easy to miss some; don't hesitate to hunt them down by
20+
whatever means necessary!
21+
22+
Other projects in Rust maintain similar entry-level tasks, including
23+
the web browser [Servo], the HTTP library [hyper], the
24+
source-formatter [rustfmt], and the lint collection [clippy].
25+
26+
While Rust has an [extensive test suite][test] there is always more to
27+
test. The [E-needstest] label indicates issues that are thought to be
28+
fixed but don't have tests. Writing test cases is a great way to
29+
understand a new project and get started contributing.
30+
31+
Rust is always in need of people to [triage] issues: reproduce bugs,
32+
minimize test cases, apply labels, close resolved issues. Note that
33+
you'll need elevated GitHub permissions to apply labels, but this is
34+
easy to obtain for somebody with a bit of experience in the
35+
project. Ask a [team member][team].
36+
37+
Once you've found your way around the project and have created a few
38+
pull requests in a particular area, consider reviewing others' pull
39+
requests: good reviewership is a rare skill and always appreciated. No
40+
prior permission is needed — just start constructively and politely
41+
commenting on pull requests that interest you. If you want training
42+
on conducting good code reviews [read this guide][reviews].
43+
44+
<!--
45+
TODO: weekly triage email?
46+
TODO: @nrc says suggesting everybody review w/o training is bad
47+
-->
48+
49+
[@mentioning]: https://github.com/blog/821
50+
[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
51+
[E-mentor]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
52+
[E-needstest]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-needstest
53+
[PR]: https://github.com/rust-lang/rust/pulls
54+
[Servo]: https://github.com/servo/servo
55+
[clippy]: https://github.com/Manishearth/rust-clippy
56+
[hyper]: https://github.com/hyperium/hyper
57+
[issue tracker]: https://github.com/rust-lang/rust/issues
58+
[pull]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#pull-requests
59+
[reviews]: http://blog.originate.com/blog/2014/09/29/effective-code-reviews/
60+
[rustfmt]: https://github.com/nrc/rustfmt
61+
[team]: team.html
62+
[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
63+
[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage

‎contribute-community.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
layout: default
3+
title: Contributing to Rust &mdash; community building &middot; The Rust Programming Language
4+
---
5+
6+
# Contributing to Rust &mdash; community building
7+
8+
Help newbies, spread the word, meet interesting people. Make Rust the
9+
shining example of open source development that we all want it to be.
10+
11+
Keep an eye on the [#rust-beginners] channel. This is where we direct
12+
new Rust programmers to ask for help, and it is vital when they do
13+
that they receive prompt, accurate, and courteous responses. Likewise,
14+
[Stack Overflow], [users.rust-lang.org], and [/r/rust], are all forums
15+
where Rust programers commonly look for assistance. If you want
16+
training on answering programmers' questions [read this
17+
guide][helpful].
18+
19+
If you are already experienced in some area of the project, please
20+
look out for potential [E-easy] bugs. When you see an
21+
easy issue on the bug tracker that you know how to fix, write up a
22+
description of the fix and tag it with E-easy. Note that what is
23+
obvious to you is not obvious to a new Rust contributor, and its
24+
important to describe the problem and the solution clearly. It is
25+
thus also helpful to triage E-easy bugs for poor descrptions and
26+
improve them.
27+
28+
Experienced developers who are patient and communicate clearly should
29+
consider [mentoring new contributors][mentor]. Tag easy issues with
30+
[E-mentor] and mention in a comment that you will mentor. Expect people
31+
to contact you about the issue, and attempt to respond promptly.
32+
33+
Maintaining entry-level tasks is good not only for The Rust Project
34+
itself but all projects. If your project has a consistent supply of
35+
entry-level tasks you might institute such a program
36+
yourself. ***Curating entry-level tasks is one of the most effective
37+
methods of bringing new programmers into the project***.
38+
39+
Talk about what you are working on in the weekly "what's everyone
40+
working on this week" threads on [/r/rust] and [users.rust-lang.org],
41+
and indicate what you need help with. These are great starting points
42+
for collaboration.
43+
44+
Advocate Rust in your own local community. Rust [user groups] and [events]
45+
are a unique and exciting part of the Rust experience: there are so
46+
many, and they are everywhere! If you haven't been yet, go and enjoy
47+
new experiences. If there is nothing Rusty going on near you then
48+
consider organizing something. You can poll for interest and announce
49+
events on [/r/rust] or [users.rust-lang.org]. Contact the [community
50+
team] to put events on the calendar, and thus be announced on [This
51+
Week in Rust].
52+
53+
Remember as you are advocating Rust though to be considerate of
54+
others' views &mdash; not everybody is going to be receptive to Rust, and
55+
that's just fine.
56+
57+
Meet other Rust community builders in [#rust-community].
58+
59+
<!--
60+
Other ideas:
61+
TWIR, podcasts.
62+
63+
experience reports
64+
conf talks
65+
66+
Conduct training on Rust. (link to training material).
67+
-->
68+
69+
[#rust-beginners]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-beginners
70+
[#rust-community]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-community
71+
[/r/rust]: https://reddit.com/r/rust
72+
[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
73+
[E-mentor]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
74+
[Stack Overflow]: http://stackoverflow.com/questions/tagged/rust
75+
[This Week in Rust]: http://www.this-week-in-rust.org
76+
[community team]: https://www.rust-lang.org/team.html#Community
77+
[events]: https://www.google.com/calendar/[email protected]
78+
[helpful]: http://blogs.msmvps.com/jonskeet/2009/02/17/answering-technical-questions-helpfully/
79+
[mentor]: https://users.rust-lang.org/t/mentoring-newcomers-to-the-rust-ecosystem/3088
80+
[user groups]: user_groups.html
81+
[users.rust-lang.org]: https://users.rust-lang.org

‎contribute-compiler.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
layout: default
3+
title: Contributing to Rust &mdash; language, compiler, and the standard library &middot; The Rust Programming Language
4+
---
5+
6+
# Contributing to Rust &mdash; language, compiler, and the standard library
7+
8+
9+
The source code to the compiler and standard library are in the main
10+
repository, and as their maintenance is the primary objective of that
11+
repository, many labels on the issue tracker relate to it. Some of
12+
the more fruitful labels include [A-codegen], for translation of
13+
Rust to LLVM IR; [A-debuginfo], generation of metadata used by debuggers;
14+
[A-diagnostics], the feedback the compiler provides on errors; [A-libs],
15+
issues with the standard library; [A-macros] and [A-syntaxext], both
16+
related to syntax extensions; and [A-typesystem], on the topic of types.
17+
18+
There is no well-maintained guide to the architecture of the compiler,
19+
but [there is a small overview in-tree][rustc-guide]. The [API
20+
documentation for the crates that make up the
21+
compiler][internals-docs] can help with navigating the code, as can
22+
the source code browser [Rust DXR]. The [guide to the Rust test
23+
suite][testsuite] will teach you how to exercise the Rust build system
24+
effectively, as will running [`make tips`][tips] at the command line.
25+
26+
For the foreseable future, one of the major thrusts of Rust compiler
27+
development is converting its internals from operating directly off
28+
the AST to working with an [intermediate representation called
29+
MIR][mir]. This work is expected to open up many new possibilities by
30+
simplifying the compiler and help is needed to e.g. create a MIR-based
31+
translation pass, add MIR-based optimizations, and implement
32+
incremental compilation. There is yet no single source for information
33+
on work needed here, but ask on [internals.rust-lang.org] or
34+
[#rust-internals] for guidance.
35+
36+
[It's embarrasing when our compiler crashes][ice] &mdash; the
37+
dreaded 'internal compiler error' (ICE). The [I-ICE] label
38+
tracks these, and they are often plentiful. These are usually
39+
good bugs to start with because it's easy to know when you've fixed
40+
them, and they're often relatively self-contained.
41+
42+
The performance of Rust code is one of its great advantages; and the
43+
performance of the Rust compiler one of its great weaknesses. Any
44+
improvements to either runtime or &mdash; especially &mdash; compiletime performance
45+
are widely celebrated. The [I-slow] and [A-optimization] labels deal
46+
with runtime performance, and [I-compiletime] with compiletime. We have
47+
a [site that tracks compiletime performance][rustc-perf] on a number
48+
of workloads. The `-Z time-passes` compiler flag can help debug
49+
compiler performance, and Rust code can be profiled with standard
50+
profilers like `perf` on Linux.
51+
52+
Major new features go through a [Request for Comments (RFC)][rfc]
53+
process, by which the design is agreed upon. Though it is open to all,
54+
it is a social process between developers who already have various
55+
amounts of experience working together, and it is recommended to get
56+
involved slowly &mdash; submitting a hasty RFC without understanding
57+
the historical, technical, or social context is an easy way
58+
to make a poor impression and come away disappointed. Read the
59+
aforelinkd readme file to understand best how it all works. Many
60+
ideas have been debated in Rust's history, some rejected, some
61+
postponed until the future, and the RFC [issue tracker][rfc-issues]
62+
catalogs some wishlist ideas that have yet to make headway into the
63+
language. Shortly before an RFC is accepted for implementation it
64+
enters 'final commemnt period', indicated by the [final-comment-period
65+
label on the rust-lang/rfcs repository][rfc-fcp]. Likewise, before a
66+
feature is enabled in the stable compiler (called 'ungating') it
67+
enters [final-comment-period in the rust-lang/rust
68+
repository][issue-fcp]. Both FCPs are critical moments to get involved
69+
and express opinions on the direction of the language, and are
70+
advertised in the weekly subteam reports on [internals.rust-lang.org].
71+
72+
Meet other Rust compiler engineers in [#rustc], language
73+
designers in [#rust-lang], and library designers in [#rust-libs].
74+
75+
<!--
76+
TODO: guide to compile-time benchmarking
77+
TODO: using the triage bot?
78+
TODO: some of this RFC description could probably go in the RFC readme
79+
-->
80+
81+
82+
[#rust-internals]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals
83+
[#rust-lang]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-lang
84+
[#rust-libs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-libs
85+
[#rustc]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc
86+
[A-codegen]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-codegen
87+
[A-debuginfo]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-debuginfo
88+
[A-diagnostics]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-diagnostics
89+
[A-libs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-libs
90+
[A-macros]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-macros
91+
[A-optimization]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-optimization
92+
[A-syntaxext]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-syntaxext
93+
[A-typesystem]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-typesystem
94+
[I-ICE]: https://github.com/rust-lang/rust/labels/I-ICE
95+
[I-compiletime]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-compiletime
96+
[I-slow]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-slow
97+
[Rust DXR]: https://dxr.mozilla.org/rust/source/src
98+
[ice]: https://users.rust-lang.org/t/glacier-a-big-ol-pile-of-ice/3380
99+
[internals-docs]: http://manishearth.github.com/rust-internals-docs
100+
[internals.rust-lang.org]: https://internals.rust-lang.org/
101+
[issue-fcp]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AB-unstable+label%3Afinal-comment-period
102+
[mir]: https://github.com/rust-lang/rust/issues/27840
103+
[rfc-fcp]: https://github.com/rust-lang/rfcs/pulls?q=is%3Aopen+is%3Apr+label%3Afinal-comment-period
104+
[rfc-issues]: https://github.com/rust-lang/rfcs/issues
105+
[rfc]: https://github.com/rust-lang/rfcs#table-of-contents
106+
[rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md
107+
[rustc-perf]: http://ncameron.org/perf-rustc/
108+
[testsuite]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
109+
[tips]: https://github.com/rust-lang/rust/blob/3d1f3c9d389d46607ae28c51cc94c1f43d65f3f9/Makefile.in#L48

‎contribute-docs.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
layout: default
3+
title: Contributing to Rust &mdash; documentation &middot; The Rust Programming Language
4+
---
5+
6+
# Contributing to Rust &mdash; documentation
7+
8+
Documentation is never good enough and there's never enough of it.
9+
Many aspects of Rust's documentation don't require deep knowledge to
10+
improve, and writing, reviewing, and editing documentation are great
11+
ways to learn Rust. Furthermore, improvements to documentation are
12+
easy to identify and limitless. Don't like the way something reads?
13+
Discover some information that wasn't documented? Your pull request
14+
will be gleefully embraced.
15+
16+
***The most impactful documentation you can write is [for the crates
17+
that make up the Rust ecosystem][crate_docs]***. While the in-tree
18+
documentation is relatively complete, the same is not yet true for
19+
[many of the popular crates and tools][awesome-rust] that Rust
20+
programmers interact with every day. Contributing API documentation to
21+
a popular Rust project will earn you the enduring love of its maintainer.
22+
23+
[The Book] is the primary documentation for Rust, maintained in the
24+
main repository. It has its own issue label, [A-book] and
25+
is continually being refined. Other documentation in the main
26+
repository include [The Rust Reference], the [standard library API
27+
documentation][std], [The Rustonomicon] (a guide to using `unsafe`
28+
correctly). The [Rust Style Guidelines] are so incomplete they are not
29+
linked prominently; an ambitious contributor can make much headway
30+
there. The [error index][err] provides extended explanations of the
31+
errors produced by the compiler. As new errors are added this
32+
documentation [must be maintained][err-issue], so there always
33+
errors not reflected in the index to be added. Most in-tree
34+
documentation lives in the [src/doc] directory. To contribute simply
35+
edit it and submit a pull request. These are all covered by the
36+
[A-docs] label on the issue tracker.
37+
38+
A great deal of important Rust documentation does not live in the main
39+
repository, or is not maintained by the project, but is still
40+
critically important to Rust's success. Examples of excellent Rust
41+
documentation that is actively developed and in need of contributors
42+
include [Rust By Example], [Rust Design Patterns], and [rust-rosetta].
43+
For other existing documentation projects to contribute to see [rust-learning].
44+
45+
Meet other Rust documentarians in [#rust-docs].
46+
47+
<!--
48+
TODO: blogging, translation
49+
-->
50+
51+
[#rust-docs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-docs
52+
[A-book]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book
53+
[A-docs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs
54+
[Rust By Example]: https://github.com/rust-lang/rust-by-example
55+
[Rust Design Patterns]: https://github.com/nrc/patterns
56+
[Rust Style Guidelines]: http://doc.rust-lang.org/style/index.html
57+
[The Book]: http://doc.rust-lang.org/book/index.html
58+
[The Rust Reference]: http://doc.rust-lang.org/reference.html
59+
[The Rustonomicon]: http://doc.rust-lang.org/nomicon/index.html
60+
[awesome-rust]: https://github.com/kud1ing/awesome-rust
61+
[crate_docs]: https://users.rust-lang.org/t/lets-talk-about-ecosystem-documentation/2791
62+
[err-issue]: https://github.com/rust-lang/rust/issues/24407
63+
[err]: http://doc.rust-lang.org/error-index.html
64+
[rust-learning]: https://github.com/ctjhoa/rust-learning
65+
[rust-rosetta]: https://github.com/Hoverbear/rust-rosetta
66+
[src/doc]: https://github.com/rust-lang/rust/tree/master/src/doc
67+
[std]: http://doc.rust-lang.org/std/index.html

0 commit comments

Comments
 (0)