Contributions page

.gitignore

@@ -1,3 +1,4 @@
 _site
 Gemfile.lock
 serve/
+*~

_layouts/default.html

@@ -49,6 +49,9 @@
 	  <li>
 	    <a href="community.html">Community</a>
 	  </li>
+	  <li>
+	    <a href="contribute.html">Contributing</a>
+	  </li>
           <li>
             <a href="legal.html">Legal</a>
           </li>

community.md

@@ -129,6 +129,7 @@ socialize with other people with a similar interest. Meetings are
 usually held monthly and very informal. Meetings are open to everyone.
 
 There is a global [calendar][calendar] for keeping up with Rust events.
+Contact the [community team][community_team] to add your own.
 
 [user_group]: ./user_groups.html
 [calendar]: https://www.google.com/calendar/[email protected]
@@ -179,12 +180,11 @@ help get you started.
 [community_team]: https://www.rust-lang.org/team.html#Community
 [mod_team]: https://www.rust-lang.org/team.html#Moderation
 
+<a name="rust-development"></a>
 ## Rust Development
 
 Rust has had over [1,200 different contributors][authors], a number that grows
-every single week. We'd love for you to join that list! If you aren't sure what
-to work on or how to get started, take a look at our
-[how to contribute][contribute] page.
+every single week. [We'd love for you to join that list][contribute]!
 
 As mentioned above, the [Rust Internals Forum][internals_forum] is dedicated to
 discussing the design and implementation of Rust. A lot of discussion also
@@ -203,7 +203,7 @@ team business, including the progression of proposals through the RFC and
 implementation process.
 
 [authors]: https://github.com/rust-lang/rust/blob/master/AUTHORS.txt
-[contribute]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
+[contribute]: contribute.html
 [github]: https://github.com/rust-lang/rust
 [rfcs]: https://github.com/rust-lang/rfcs
 [team_reports]: https://github.com/rust-lang/subteams

contribute-bugs.md

@@ -0,0 +1,63 @@
+---
+layout: default
+title: Contributing to Rust — finding, triaging and fixing issues · The Rust Programming Language
+---
+
+# Contributing to Rust — finding, triaging and fixing issues
+
+The day-to-day maintenance of the project revolves around Rust's
+[issue tracker] and [pull requests][PR], and more help is always
+needed. The most basic way to get started contributing to Rust is to
+look for the [E-easy] or [E-mentor] labels. These are meant to be
+approachable for new Rust programmers.
+
+On `E-mentor` issues an experienced Rust developer has volunteered in
+the comments to mentor you through solving the issue and [submitting
+the fix via GitHub pull request][pull]. Contact them about the issue,
+on the issue tracker by [@mentioning] their name in a comment, on IRC,
+or through email. Note that Rust developers get a lot of notifications
+and it is easy to miss some; don't hesitate to hunt them down by
+whatever means necessary!
+
+Other projects in Rust maintain similar entry-level tasks, including
+the web browser [Servo], the HTTP library [hyper], the
+source-formatter [rustfmt], and the lint collection [clippy].
+
+While Rust has an [extensive test suite][test] there is always more to
+test. The [E-needstest] label indicates issues that are thought to be
+fixed but don't have tests. Writing test cases is a great way to
+understand a new project and get started contributing.
+
+Rust is always in need of people to [triage] issues: reproduce bugs,
+minimize test cases, apply labels, close resolved issues. Note that
+you'll need elevated GitHub permissions to apply labels, but this is
+easy to obtain for somebody with a bit of experience in the
+project. Ask a [team member][team].
+
+Once you've found your way around the project and have created a few
+pull requests in a particular area, consider reviewing others' pull
+requests: good reviewership is a rare skill and always appreciated. No
+prior permission is needed — just start constructively and politely
+commenting on pull requests that interest you. If you want training
+on conducting good code reviews [read this guide][reviews].
+
+<!--
+TODO: weekly triage email?
+TODO: @nrc says suggesting everybody review w/o training is bad
+-->
+
+[@mentioning]: https://github.com/blog/821
+[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
+[E-mentor]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
+[E-needstest]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-needstest
+[PR]: https://github.com/rust-lang/rust/pulls
+[Servo]: https://github.com/servo/servo
+[clippy]: https://github.com/Manishearth/rust-clippy
+[hyper]: https://github.com/hyperium/hyper
+[issue tracker]: https://github.com/rust-lang/rust/issues
+[pull]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#pull-requests
+[reviews]: http://blog.originate.com/blog/2014/09/29/effective-code-reviews/
+[rustfmt]: https://github.com/nrc/rustfmt
+[team]: team.html
+[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
+[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage

contribute-community.md

@@ -0,0 +1,84 @@
+---
+layout: default
+title: Contributing to Rust — community building · The Rust Programming Language
+---
+
+# Contributing to Rust — community building
+
+Help newbies, spread the word, meet interesting people. Make Rust the
+shining example of open source development that we all want it to be.
+
+Keep an eye on the [#rust-beginners] channel. This is where we direct
+new Rust programmers to ask for help, and it is vital when they do
+that they receive prompt, accurate, and courteous responses. Likewise,
+[Stack Overflow], [users.rust-lang.org], and [/r/rust], are all forums
+where Rust programers commonly look for assistance. If you want
+training on answering programmers' questions [read this
+guide][helpful].
+
+If you are already experienced in some area of the project, please
+look out for potential [E-easy] bugs. When you see an
+easy issue on the bug tracker that you know how to fix, write up a
+description of the fix and tag it with E-easy. Note that what is
+obvious to you is not obvious to a new Rust contributor, and its
+important to describe the problem and the solution clearly. It is
+thus also helpful to triage E-easy bugs for poor descrptions and
+improve them.
+
+Experienced developers who are patient and communicate clearly should
+consider [mentoring new contributors][mentor]. Tag easy issues with
+[E-mentor] and mention in a comment that you will mentor. Expect people
+to contact you about the issue, and attempt to respond promptly.
+
+Maintaining entry-level tasks is good not only for The Rust Project
+itself but all projects. If your project has a consistent supply of
+entry-level tasks you might institute such a program
+yourself. ***Curating entry-level tasks is one of the most effective
+methods of bringing new programmers into the project***. If you want
+training on mentoring new contributors [read this
+guide][mentor-guide].
+
+Talk about what you are working on in the weekly "what's everyone
+working on this week" threads on [/r/rust] and [users.rust-lang.org],
+and indicate what you need help with. These are great starting points
+for collaboration.
+
+Advocate Rust in your own local community. Rust [user groups] and [events]
+are a unique and exciting part of the Rust experience: there are so
+many, and they are everywhere! If you haven't been yet, go and enjoy
+new experiences. If there is nothing Rusty going on near you then
+consider organizing something. You can poll for interest and announce
+events on [/r/rust] or [users.rust-lang.org]. Contact the [community
+team] to put events on the calendar, and thus be announced on [This
+Week in Rust].
+
+Remember as you are advocating Rust though to be considerate of
+others' views — not everybody is going to be receptive to Rust, and
+that's just fine.
+
+Meet other Rust community builders in [#rust-community].
+
+<!--
+Other ideas:
+TWIR, podcasts.
+
+experience reports
+conf talks
+
+Conduct training on Rust. (link to training material).
+-->
+
+[#rust-beginners]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-beginners
+[#rust-community]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-community
+[/r/rust]: https://reddit.com/r/rust
+[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
+[E-mentor]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
+[Stack Overflow]: http://stackoverflow.com/questions/tagged/rust
+[This Week in Rust]: http://www.this-week-in-rust.org
+[community team]: https://www.rust-lang.org/team.html#Community
+[events]: https://www.google.com/calendar/[email protected]
+[helpful]: http://blogs.msmvps.com/jonskeet/2009/02/17/answering-technical-questions-helpfully/
+[mentor]: https://users.rust-lang.org/t/mentoring-newcomers-to-the-rust-ecosystem/3088
+[mentor-guide]: http://manishearth.github.io/blog/2016/01/03/making-your-open-source-project-newcomer-friendly/
+[user groups]: user_groups.html
+[users.rust-lang.org]: https://users.rust-lang.org

contribute-compiler.md

@@ -0,0 +1,109 @@
+---
+layout: default
+title: Contributing to Rust — language, compiler, and the standard library · The Rust Programming Language
+---
+
+# Contributing to Rust — language, compiler, and the standard library
+
+
+The source code to the compiler and standard library are in the main
+repository, and as their maintenance is the primary objective of that
+repository, many labels on the issue tracker relate to it. Some of
+the more fruitful labels include [A-codegen], for translation of
+Rust to LLVM IR; [A-debuginfo], generation of metadata used by debuggers;
+[A-diagnostics], the feedback the compiler provides on errors; [A-libs],
+issues with the standard library; [A-macros] and [A-syntaxext], both
+related to syntax extensions; and [A-typesystem], on the topic of types.
+
+There is no well-maintained guide to the architecture of the compiler,
+but [there is a small overview in-tree][rustc-guide]. The [API
+documentation for the crates that make up the
+compiler][internals-docs] can help with navigating the code, as can
+the source code browser [Rust DXR]. The [guide to the Rust test
+suite][testsuite] will teach you how to exercise the Rust build system
+effectively, as will running [`make tips`][tips] at the command line.
+
+For the foreseable future, one of the major thrusts of Rust compiler
+development is converting its internals from operating directly off
+the AST to working with an [intermediate representation called
+MIR][mir]. This work is expected to open up many new possibilities by
+simplifying the compiler and help is needed to e.g. create a MIR-based
+translation pass, add MIR-based optimizations, and implement
+incremental compilation. There is yet no single source for information
+on work needed here, but ask on [internals.rust-lang.org] or
+[#rust-internals] for guidance.
+
+[It's embarrasing when our compiler crashes][ice] — the
+dreaded 'internal compiler error' (ICE). The [I-ICE] label
+tracks these, and they are often plentiful. These are usually
+good bugs to start with because it's easy to know when you've fixed
+them, and they're often relatively self-contained.
+
+The performance of Rust code is one of its great advantages; and the
+performance of the Rust compiler one of its great weaknesses. Any
+improvements to either runtime or — especially — compiletime performance
+are widely celebrated. The [I-slow] and [A-optimization] labels deal
+with runtime performance, and [I-compiletime] with compiletime. We have
+a [site that tracks compiletime performance][rustc-perf] on a number
+of workloads. The `-Z time-passes` compiler flag can help debug
+compiler performance, and Rust code can be profiled with standard
+profilers like `perf` on Linux.
+
+Major new features go through a [Request for Comments (RFC)][rfc]
+process, by which the design is agreed upon. Though it is open to all,
+it is a social process between developers who already have various
+amounts of experience working together, and it is recommended to get
+involved slowly — submitting a hasty RFC without understanding
+the historical, technical, or social context is an easy way
+to make a poor impression and come away disappointed. Read the
+aforelinkd readme file to understand best how it all works. Many
+ideas have been debated in Rust's history, some rejected, some
+postponed until the future, and the RFC [issue tracker][rfc-issues]
+catalogs some wishlist ideas that have yet to make headway into the
+language. Shortly before an RFC is accepted for implementation it
+enters 'final commemnt period', indicated by the [final-comment-period
+label on the rust-lang/rfcs repository][rfc-fcp]. Likewise, before a
+feature is enabled in the stable compiler (called 'ungating') it
+enters [final-comment-period in the rust-lang/rust
+repository][issue-fcp]. Both FCPs are critical moments to get involved
+and express opinions on the direction of the language, and are
+advertised in the weekly subteam reports on [internals.rust-lang.org].
+
+Meet other Rust compiler engineers in [#rustc], language
+designers in [#rust-lang], and library designers in [#rust-libs].
+
+<!--
+TODO: guide to compile-time benchmarking
+TODO: using the triage bot?
+TODO: some of this RFC description could probably go in the RFC readme
+-->
+
+
+[#rust-internals]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals
+[#rust-lang]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-lang
+[#rust-libs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-libs
+[#rustc]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc
+[A-codegen]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-codegen
+[A-debuginfo]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-debuginfo
+[A-diagnostics]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-diagnostics
+[A-libs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-libs
+[A-macros]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-macros
+[A-optimization]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-optimization
+[A-syntaxext]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-syntaxext
+[A-typesystem]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-typesystem
+[I-ICE]: https://github.com/rust-lang/rust/labels/I-ICE
+[I-compiletime]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-compiletime
+[I-slow]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-slow
+[Rust DXR]: https://dxr.mozilla.org/rust/source/src
+[ice]: https://users.rust-lang.org/t/glacier-a-big-ol-pile-of-ice/3380
+[internals-docs]: http://manishearth.github.com/rust-internals-docs
+[internals.rust-lang.org]: https://internals.rust-lang.org/
+[issue-fcp]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AB-unstable+label%3Afinal-comment-period
+[mir]: https://github.com/rust-lang/rust/issues/27840
+[rfc-fcp]: https://github.com/rust-lang/rfcs/pulls?q=is%3Aopen+is%3Apr+label%3Afinal-comment-period
+[rfc-issues]: https://github.com/rust-lang/rfcs/issues
+[rfc]: https://github.com/rust-lang/rfcs#table-of-contents
+[rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md
+[rustc-perf]: http://ncameron.org/perf-rustc/
+[testsuite]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
+[tips]: https://github.com/rust-lang/rust/blob/3d1f3c9d389d46607ae28c51cc94c1f43d65f3f9/Makefile.in#L48

contribute-docs.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Contributing to Rust — documentation · The Rust Programming Language
+---
+
+# Contributing to Rust — documentation
+
+Documentation is never good enough and there's never enough of it.
+Many aspects of Rust's documentation don't require deep knowledge to
+improve, and writing, reviewing, and editing documentation are great
+ways to learn Rust. Furthermore, improvements to documentation are
+easy to identify and limitless. Don't like the way something reads?
+Discover some information that wasn't documented?  Your pull request
+will be gleefully embraced.
+
+***The most impactful documentation you can write is [for the crates
+that make up the Rust ecosystem][crate_docs]***. While the in-tree
+documentation is relatively complete, the same is not yet true for
+[many of the popular crates and tools][awesome-rust] that Rust
+programmers interact with every day. Contributing API documentation to
+a popular Rust project will earn you the enduring love of its maintainer.
+
+[The Book] is the primary documentation for Rust, maintained in the
+main repository. It has its own issue label, [A-book] and
+is continually being refined. Other documentation in the main
+repository include [The Rust Reference], the [standard library API
+documentation][std], [The Rustonomicon] (a guide to using `unsafe`
+correctly). The [Rust Style Guidelines] are so incomplete they are not
+linked prominently; an ambitious contributor can make much headway
+there. The [error index][err] provides extended explanations of the
+errors produced by the compiler. As new errors are added this
+documentation [must be maintained][err-issue], so there always
+errors not reflected in the index to be added. Most in-tree
+documentation lives in the [src/doc] directory. To contribute simply
+edit it and submit a pull request. These are all covered by the
+[A-docs] label on the issue tracker.
+
+A great deal of important Rust documentation does not live in the main
+repository, or is not maintained by the project, but is still
+critically important to Rust's success. Examples of excellent Rust
+documentation that is actively developed and in need of contributors
+include [Rust By Example], [Rust Design Patterns], and [rust-rosetta].
+For other existing documentation projects to contribute to see [rust-learning].
+
+Meet other Rust documentarians in [#rust-docs].
+
+<!--
+TODO: blogging, translation
+-->
+
+[#rust-docs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-docs
+[A-book]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book
+[A-docs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs
+[Rust By Example]: https://github.com/rust-lang/rust-by-example
+[Rust Design Patterns]: https://github.com/nrc/patterns
+[Rust Style Guidelines]: http://doc.rust-lang.org/style/index.html
+[The Book]: http://doc.rust-lang.org/book/index.html
+[The Rust Reference]: http://doc.rust-lang.org/reference.html
+[The Rustonomicon]: http://doc.rust-lang.org/nomicon/index.html
+[awesome-rust]: https://github.com/kud1ing/awesome-rust
+[crate_docs]: https://users.rust-lang.org/t/lets-talk-about-ecosystem-documentation/2791
+[err-issue]: https://github.com/rust-lang/rust/issues/24407
+[err]: http://doc.rust-lang.org/error-index.html
+[rust-learning]: https://github.com/ctjhoa/rust-learning
+[rust-rosetta]: https://github.com/Hoverbear/rust-rosetta
+[src/doc]: https://github.com/rust-lang/rust/tree/master/src/doc
+[std]: http://doc.rust-lang.org/std/index.html