From c5b06defcd5e7ab15113b003a3919947b9a2277e Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Sat, 17 Oct 2015 19:48:19 +0900 Subject: [PATCH 01/10] Added contribution page --- contributions.md | 177 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 contributions.md diff --git a/contributions.md b/contributions.md new file mode 100644 index 000000000..d26fe032c --- /dev/null +++ b/contributions.md @@ -0,0 +1,177 @@ +--- +layout: default +title: How To Contribute +--- + +# Contributing to Rust + +If you're learning Rust, you've no doubt been amazed at how awesome +the language is and will be keen to write more Rust code. Hopefully, +you'll also want to make a meaningful contribution to the community. +If you're not sure how best to do that, then hopefully this page will +help. Most of this page is filled with links to lists of issues to +help you find something to work on. There are issues on the Rust +project itself, a number of supporting projects, and some projects +which are large users of Rust. + +Writing code isn't the only way to make a meaningful contribution. +Writing tests and documentation is how many people get started and is +really useful. There are links to these kind of issues too. Likewise +finding bugs and filing issues in any of the projects linked here is +very much appreciated. As a reminder, all contributors are expected to +follow our [Code of Conduct][coc]. + +[coc]: https://www.rust-lang.org/conduct.html + +## Finding Something to Work On + +#### Issues + +If you're looking for [issues][rust_issues] on the Rust repo +and want something easy-ish to start with, look for the [E-easy][e_easy_issues] +or [E-mentor][e_mentor_issues] labels. + +Contributors with sufficient permissions on the Rust repo can help by +adding labels to triage issues: + +- **Yellow A-prefixed** labels state which area of the project an + issue relates to. +- **Magenta B-prefixed** labels identify bugs which belong elsewhere. +- **Green E-prefixed** labels explain the level of experience + necessary to fix the issue. +- **Red I-prefixed** labels indicate the importance of the issue. The + I-nominated label indicates that an issue has been nominated for +prioritizing at the next triage meeting. +- **Orange P-prefixed** labels indicate a bug's priority. These labels + are only assigned during triage meetings, and replace the +I-nominated label. +- **Blue T-prefixed** bugs denote which team the issue belongs to. +- **Dark blue beta-** labels track changes which need to be backported + into the beta branches. +- **Purple** metabug labels mark lists of bugs collected by other + categories. + +[rust_issues]: https://github.com/rust-lang/rust/issues +[e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy +[e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor + +#### The Rust compiler + +The compiler is part of the [main repo][main_repo], which also +includes the standard library crates and a whole bunch of supporting +code. For questions about the compiler, there is the +[#rustc][rustc_irc] IRC channel. Compiler errors (ICE for 'internal +compiler errors') can be searched for in issues using the +[I-ICE][i_ice_issues] label. 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. If you're interested in parsing, macros, +syntactic stuff, the [parsing][parsing_issues] label and the +[macro][macro_issues] label are a good places to start. + +[main_repo]: https://github.com/rust-lang +[rust_irc]: irc://moznet/rustc +[i_ice_issues]: https://github.com/rust-lang/rust/labels/I-ICE +[parsing_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser +[macro_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser+label%3AA-macros + +#### Standard Libraries + +[Libstd][libstd], [libcollections][libcollections], +[liballoc][liballoc] and [libcore][libcore] are the main library +crates. These all appear to users as if they are part of libstd, the +standard library. These tend to be very fundamental libraries - +built-in types, low level IO and concurrency, allocation, essential +collections, and so forth. You should join [#rust-libs][libs_irc] if +you are interested in contributing to the Rust libraries. + +[libstd]: https://github.com/rust-lang/rust/tree/master/src/libstd +[libcollections]: https://github.com/rust-lang/rust/tree/master/src/libcollections +[liballoc]: https://github.com/rust-lang/rust/tree/master/src/liballoc +[libcore]: https://github.com/rust-lang/rust/tree/master/src/libcore +[libs_irc]: irc://moznet/rust-libs + +#### Cargo + +[Cargo][cargo_issues] is Rust's package manager. + +[cargo_issues]: https://github.com/rust-lang/cargo/issues + +#### Tests + +Contributing tests is extremely valuable to the Rust project. For the +compiler and standard libraries, there are unit tests (usually) +embedded in the source code and regression tests in the +[src/tests][tests] directory. There is a list of issues which have +(probably) been fixed, but still need a test. Nearly any other project +will be extremely welcoming of new tests too. Writing test cases is a +great way to begin to understand a new project and get started +contributing. + +[test]: https://github.com/rust-lang/rust/tree/master/src/test + +#### Checking Older Bugs + +Sometimes, an issue will stay open, even though the bug has been +fixed. And sometimes, the original bug may go stale because something +has changed in the meantime. It can be helpful to go through older bug +reports and make sure that they are still valid. Load up an older +issue, double check that it's still true, and leave a comment letting +us know if it is or is not. The [least recently updated][lru_issues] +sort is good for finding issues like this. + +[lru_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc + +#### Documentation + +Documentation is never good enough and there's never enough of it. +Writing docs is a really valuable way to contribute to open source +projects. Many aspects of the docs don't require super-deep knowledge, +especially if they're aimed at newcomers. It's also a great way to +learn more about the language or specific libraries. + +- [The Book][rustbook_issues] The main guide to learning Rust. +- [Rust Documentation][rustdoc_issues] +- [Rust by Example][rust_by_example_issues] +- [Rust for C++ Programmers][rust_for_cpp_issues] A tutorial aimed +at experienced C++ programmers coming to Rust. + +[rustbook_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book +[rustdoc_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs +[rust_by_example_issues]: https://github.com/rust-lang/rust-by-example/issues +[rust_for_cpp_issues]: https://github.com/nrc/r4cppp/issues + +#### Tools + +Tools play a huge part in the success of a language. Rust has some +great tool support, in particular with debugging and package +management, but we need much more. + +- [cargo](https://github.com/rust-lang/cargo/issues) Rust's package manager and build system. +- [rustdoc](https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc) + Produces documentation for the official libraries and user projects. +- [racer](https://github.com/phildawes/racer) Code completion. +- [rustfmt](https://github.com/nrc/rustfmt) Code formatting. +- [multirust](https://github.com/brson/multirust/issues) For managing + multiple installations of the Rust toolchain. +- [homu](https://github.com/barosl/homu/issues) Acts as a gatekeeper for commits. + +#### Other Contributions + +Try [Github Trending][trending] for currently active Rust projects. +There are a number of other ways to contribute to Rust that don't deal +directly with the Rust repository. + +- Answer questions in [#rust][rust_irc], on the [Rust Forum][forum] or + on [Stack Overflow][stack_overflow]. +- Participate in the [RFC process][rfcs]. +- Find a [requested community library][requested], build it, and + publish it to [Crates.io][crates]. Easier said than done, +but very, very valuable! + +[trending]: https://github.com/trending?l=rust +[rust_irc]: irc://moznet/rust +[forum]: https://users.rust-lang.org/ +[stack_overflow]: http://stackoverflow.com/questions/tagged/rust +[rfcs]: https://github.com/rust-lang/rfcs +[requested]: https://github.com/rust-lang/rfcs/labels/A-community-library +[crates]: http://crates.io From 8fb7d957787b7f62177b5bc59a78d7ab2048f13e Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Wed, 28 Oct 2015 11:26:17 +0900 Subject: [PATCH 02/10] Added "Getting Started" to contribution.md --- contributions.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/contributions.md b/contributions.md index d26fe032c..444dde1ba 100644 --- a/contributions.md +++ b/contributions.md @@ -23,16 +23,11 @@ follow our [Code of Conduct][coc]. [coc]: https://www.rust-lang.org/conduct.html -## Finding Something to Work On +## Getting Started By Scanning Through Issues -#### Issues - -If you're looking for [issues][rust_issues] on the Rust repo -and want something easy-ish to start with, look for the [E-easy][e_easy_issues] -or [E-mentor][e_mentor_issues] labels. - -Contributors with sufficient permissions on the Rust repo can help by -adding labels to triage issues: +One way to get started is to scan through [issues][rust_issues] on +the Rust repo. To start with, look for the [E-easy][e_easy_issues] or +[E-mentor][e_mentor_issues] labels. - **Yellow A-prefixed** labels state which area of the project an issue relates to. @@ -51,10 +46,15 @@ I-nominated label. - **Purple** metabug labels mark lists of bugs collected by other categories. +Contributors with sufficient permissions on the Rust repo can help by +adding labels to triage issues. + [rust_issues]: https://github.com/rust-lang/rust/issues [e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy [e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor +## Getting Started by Topic + #### The Rust compiler The compiler is part of the [main repo][main_repo], which also From 47ba37791888b517498311ddc31c8beb97dc1429 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Mon, 2 Nov 2015 15:33:57 -0800 Subject: [PATCH 03/10] Various changes to contributions.html --- contributions.md | 214 ++++++++++++++++++++++++++--------------------- 1 file changed, 117 insertions(+), 97 deletions(-) diff --git a/contributions.md b/contributions.md index 444dde1ba..410b20c0b 100644 --- a/contributions.md +++ b/contributions.md @@ -8,108 +8,65 @@ title: How To Contribute If you're learning Rust, you've no doubt been amazed at how awesome the language is and will be keen to write more Rust code. Hopefully, you'll also want to make a meaningful contribution to the community. -If you're not sure how best to do that, then hopefully this page will -help. Most of this page is filled with links to lists of issues to -help you find something to work on. There are issues on the Rust -project itself, a number of supporting projects, and some projects -which are large users of Rust. - -Writing code isn't the only way to make a meaningful contribution. -Writing tests and documentation is how many people get started and is -really useful. There are links to these kind of issues too. Likewise -finding bugs and filing issues in any of the projects linked here is -very much appreciated. As a reminder, all contributors are expected to +If you're not sure how best to do that, then this page will +help. + +**Just want to report a bug in Rust?** [Follow the Rust bug reporting +guide][bugs]. Thanks in advance! + +[bugs]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports + +Rust is an expansive system of projects, some officially maintained +within the [rust-lang] organization on GitHub, but with many +increasingly-important efforts driven from without by its enthusiastic +community. Newcomers will be interested in [an overview of the +organization, processes, and policies of The Rust Project][dev_proc] +and the project's [CONTRIBUTING.md] file, which explains the specifics +of contributing to [rust-lang/rust]. + +There are many ways to contribute to the success of Rust: filing, +triaging and fixing bugs; writing documentation and tests; partipating +in the the design of the language and standard libraries through the +RFC process; improving compile-time and run-time performance; +spreading the tendrils of the Rust community ever-outward. + +This guide focuses on a few avenues for the new contributor: + +* [Bugs, triage, and maintenance](#bugs). Finding issues to fix, + triaging, adding test cases. +* [Documentation](#doc). Not just official documentation, but also + for crates, blog posts, and other unofficial sources. +* [Community building](#comm). Expanding the reach of Rust, and + maintaining its excellence. +* [Tooling, IDEs, and infrastructure](#tool). The hard work of making + Rust accessible to programmers of all kinds. +* [Language and compiler](#comp). Language design, feature + implementation, performance improvement. +* [Libraries](#lib). Including the standard library, but also the + equally-important unofficial crates that make Rust usable. + +As a reminder, all contributors are expected to follow our [Code of Conduct][coc]. +[dev_proc]: dev_process.html +[rust-lang]: https://github.com/rust-lang +[rust-lang/rust]: https://github.com/rust-lang/rust +[CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md [coc]: https://www.rust-lang.org/conduct.html -## Getting Started By Scanning Through Issues - -One way to get started is to scan through [issues][rust_issues] on -the Rust repo. To start with, look for the [E-easy][e_easy_issues] or -[E-mentor][e_mentor_issues] labels. - -- **Yellow A-prefixed** labels state which area of the project an - issue relates to. -- **Magenta B-prefixed** labels identify bugs which belong elsewhere. -- **Green E-prefixed** labels explain the level of experience - necessary to fix the issue. -- **Red I-prefixed** labels indicate the importance of the issue. The - I-nominated label indicates that an issue has been nominated for -prioritizing at the next triage meeting. -- **Orange P-prefixed** labels indicate a bug's priority. These labels - are only assigned during triage meetings, and replace the -I-nominated label. -- **Blue T-prefixed** bugs denote which team the issue belongs to. -- **Dark blue beta-** labels track changes which need to be backported - into the beta branches. -- **Purple** metabug labels mark lists of bugs collected by other - categories. - -Contributors with sufficient permissions on the Rust repo can help by -adding labels to triage issues. - -[rust_issues]: https://github.com/rust-lang/rust/issues -[e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy -[e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor - -## Getting Started by Topic - -#### The Rust compiler - -The compiler is part of the [main repo][main_repo], which also -includes the standard library crates and a whole bunch of supporting -code. For questions about the compiler, there is the -[#rustc][rustc_irc] IRC channel. Compiler errors (ICE for 'internal -compiler errors') can be searched for in issues using the -[I-ICE][i_ice_issues] label. 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. If you're interested in parsing, macros, -syntactic stuff, the [parsing][parsing_issues] label and the -[macro][macro_issues] label are a good places to start. - -[main_repo]: https://github.com/rust-lang -[rust_irc]: irc://moznet/rustc -[i_ice_issues]: https://github.com/rust-lang/rust/labels/I-ICE -[parsing_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser -[macro_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser+label%3AA-macros - -#### Standard Libraries - -[Libstd][libstd], [libcollections][libcollections], -[liballoc][liballoc] and [libcore][libcore] are the main library -crates. These all appear to users as if they are part of libstd, the -standard library. These tend to be very fundamental libraries - -built-in types, low level IO and concurrency, allocation, essential -collections, and so forth. You should join [#rust-libs][libs_irc] if -you are interested in contributing to the Rust libraries. - -[libstd]: https://github.com/rust-lang/rust/tree/master/src/libstd -[libcollections]: https://github.com/rust-lang/rust/tree/master/src/libcollections -[liballoc]: https://github.com/rust-lang/rust/tree/master/src/liballoc -[libcore]: https://github.com/rust-lang/rust/tree/master/src/libcore -[libs_irc]: irc://moznet/rust-libs - -#### Cargo - -[Cargo][cargo_issues] is Rust's package manager. - -[cargo_issues]: https://github.com/rust-lang/cargo/issues - -#### Tests + +## Bugs, triage, and maintenance -Contributing tests is extremely valuable to the Rust project. For the -compiler and standard libraries, there are unit tests (usually) -embedded in the source code and regression tests in the -[src/tests][tests] directory. There is a list of issues which have -(probably) been fixed, but still need a test. Nearly any other project -will be extremely welcoming of new tests too. Writing test cases is a -great way to begin to understand a new project and get started -contributing. +The day-to-day maintenance of the project revolves around Rust's +[issue tracker] and [pull requests], and more help is always +needed. -[test]: https://github.com/rust-lang/rust/tree/master/src/test +The most basic way to get started contributing to Rust is to look for +the [E-easy][e_easy_issues] or [E-mentor][e_mentor_issues] +labels. These are meant to be approachable for new Rust programmers. -#### Checking Older Bugs +Rust is always in need of people to [triage] issues: reproduce bugs, +minimize test cases, apply labels. Sometimes, an issue will stay open, even though the bug has been 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 us know if it is or is not. The [least recently updated][lru_issues] sort is good for finding issues like this. +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 begin +to understand a new project and get started contributing. For those +especially interested in testing, there are usually *entirely new +classes* of tests that need to be implemented, and asking #rust-internals +what needs to be tested can be fruitful. + +Once you've found your way around the project and have created a few +pull requests in a particular area of the project, consider actively +reviewing others' pull requests: reviewership is a rare skill and good +reviewers are always appreciated. + [lru_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc +[issue tracker]: https://github.com/rust-lang/rust/issues +[pull requests]: https://github.com/rust-lang/rust/pulls +[e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy +[e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor +[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage +[E-needstest]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-needstest +[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md -#### Documentation + +## Documentation Documentation is never good enough and there's never enough of it. Writing docs is a really valuable way to contribute to open source @@ -140,7 +118,12 @@ at experienced C++ programmers coming to Rust. [rust_by_example_issues]: https://github.com/rust-lang/rust-by-example/issues [rust_for_cpp_issues]: https://github.com/nrc/r4cppp/issues -#### Tools + + +## Community building + + +## Tooling, IDEs, and infrastructure Tools play a huge part in the success of a language. Rust has some great tool support, in particular with debugging and package @@ -155,6 +138,43 @@ management, but we need much more. multiple installations of the Rust toolchain. - [homu](https://github.com/barosl/homu/issues) Acts as a gatekeeper for commits. + +## Libraries + +[Libstd][libstd], [libcollections][libcollections], +[liballoc][liballoc] and [libcore][libcore] are the main library +crates. These all appear to users as if they are part of libstd, the +standard library. These tend to be very fundamental libraries - +built-in types, low level IO and concurrency, allocation, essential +collections, and so forth. You should join [#rust-libs][libs_irc] if +you are interested in contributing to the Rust libraries. + +[libstd]: https://github.com/rust-lang/rust/tree/master/src/libstd +[libcollections]: https://github.com/rust-lang/rust/tree/master/src/libcollections +[liballoc]: https://github.com/rust-lang/rust/tree/master/src/liballoc +[libcore]: https://github.com/rust-lang/rust/tree/master/src/libcore +[libs_irc]: irc://moznet/rust-libs + + +## Language and compiler + +The compiler is part of the [main repo][main_repo], which also +includes the standard library crates and a whole bunch of supporting +code. For questions about the compiler, there is the +[#rustc][rustc_irc] IRC channel. Compiler errors (ICE for 'internal +compiler errors') can be searched for in issues using the +[I-ICE][i_ice_issues] label. 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. If you're interested in parsing, macros, +syntactic stuff, the [parsing][parsing_issues] label and the +[macro][macro_issues] label are a good places to start. + +[main_repo]: https://github.com/rust-lang +[rust_irc]: irc://moznet/rustc +[i_ice_issues]: https://github.com/rust-lang/rust/labels/I-ICE +[parsing_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser +[macro_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser+label%3AA-macros + #### Other Contributions Try [Github Trending][trending] for currently active Rust projects. From 0eb30faf96c668f64b252ece85933d0238e39bd7 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Tue, 3 Nov 2015 12:11:51 -0800 Subject: [PATCH 04/10] Add contributing to navbar --- _layouts/default.html | 3 +++ 1 file changed, 3 insertions(+) diff --git a/_layouts/default.html b/_layouts/default.html index 0ee1e5f2a..eaebf542e 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -49,6 +49,9 @@
  • Community
    • +
  • + Contributing +
  • Legal
    • From def9c2a7a3d3d35929dde5779e47b95eae462b51 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Tue, 3 Nov 2015 13:04:26 -0800 Subject: [PATCH 05/10] Massively expand the contributing page --- _layouts/default.html | 2 +- community.md | 8 +- contribute.md | 454 ++++++++++++++++++++++++++++++++++++++++++ contributions.md | 197 ------------------ 4 files changed, 459 insertions(+), 202 deletions(-) create mode 100644 contribute.md delete mode 100644 contributions.md diff --git a/_layouts/default.html b/_layouts/default.html index eaebf542e..50ed2f934 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -50,7 +50,7 @@ Community
  • - Contributing + Contributing
  • Legal diff --git a/community.md b/community.md index d38288dbb..de72717e2 100644 --- a/community.md +++ b/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/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com @@ -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 + ## 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 diff --git a/contribute.md b/contribute.md new file mode 100644 index 000000000..6df1f68a8 --- /dev/null +++ b/contribute.md @@ -0,0 +1,454 @@ +--- +layout: default +title: Contributing to Rust · The Rust Programming Language +--- + +# Contributing to Rust + +You've started learning Rust. You love it, and you want to be a part +of it. If you're not sure how to get involved, then this page +will help. + +**Just want to report a bug in Rust?** [Follow the bug reporting +guide][bugs]. Thanks in advance! + +Rust is an expansive system of projects, the most prominent of which +are maintained by the [The Rust Project Developers][devs] in [the +rust-lang organization on GitHub][rust-lang]. Newcomers may be +interested in [an overview of the organization, processes, and +policies of The Rust Project][dev_proc] and the project's +[CONTRIBUTING.md] file, which explains the specifics of contributing +to [rust-lang/rust]. + +There are many ways to contribute to the success of Rust. +This guide focuses on a few avenues for the new contributor: + +* [Finding, triaging and fixing issues](#bugs). The basic work + of maintaining a large and active project like Rust. +* [Documentation](#docs). Not just official documentation, but also + for crates, blog posts, and other unofficial sources. +* [Community building](#community). Helping your fellow Rustacean, + and expanding the reach of Rust. +* [Tooling, IDEs and infrastructure](#tools). There's so much + to do here. +* [Libraries](#libs). Rust's suitability for any particular task + is mostly dependent on the quality libraries that exist. +* [Language, compiler and the standard library](#compiler). Language design, feature implementation, performance improvement. + +If you need additional guidance ask on [#rust-internals] or +[internals.rust-lang.org]. + +We pride ourselves on maintaining civilized discourse, and to that end +contributors are expected to follow our [Code of Conduct][coc]. If you +have questions about this please inquire with the [community team]. + + + + +## 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 the solving the issue and +[submitting the fix GitHub pull request][pull]. Contact them about the +issue, on the issue tracker by [@mentioning] their name, 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 &emdash; 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]. + + + + +## Documentation + +Documentation is never good enough and there's never enough of it, +writing documentation is a valuable way to contribute. 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][book_issues] 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]. + + + + +## 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***. + +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]. + + + + +## Tooling, IDEs, and infrastructure + +Tools play a huge part in the success of a language, and there is a +great deal left to implement. ***A major focus of Rust development now +is [improving the IDE experience][ides]***. This involves work +throughout the Rust stack, from the compiler itself through your +favorite IDE. Follow the link for more information. + +Both Cargo, the Rust package manager, and rustdoc, +the Rust documentation generator, while full-featured and functional, +suffer from a lack of developers. Rustdoc has many open issues, under +the main repository's [A-rustdoc] label. They are mostly bugs and +contributing is a matter of fixing the bug and submitting a pull +request. Cargo has [its own repository and issues][Cargo], and those +interested in contributing might want to introduce themselves in +[#cargo]. + +Although Rust can be run under both the gdb and lldb debuggers with +limited success, there are still many cases where debugging does not +work as expected. The [A-debuginfo] issue tracks these. + +For ideas for more tooling projects to contributo to see +[awesome-rust]. + +There are often other tooling projects of interest just waiting for +the right people to come along and implement them. Discuss with other +Rust tooling enthusiasts in [#rust-tools]. + + +## Libraries + +If you want to contribute to Rust by writing volumes of Rust code, +then libraries are where it's at: since Rust is a young language, +there are many types of libraries that either do not exist yet +or are incomplete and in need of improvement or competition. + +Deciding what to write that will have impact and be fun is a common +difficulty. Here are some ideas: + +* Read and participate in the weekly "what's everyone working on + this week" threads on [/r/rust] and [users.rust-lang.org]. These are + packed with exciting announcements from other Rust programmers in + need of collaborators. +* Familiarize yourself with the best Rust libraries through + [awesome-rust] and [libs.rs]. +* Some larger projects, including the web browser [Servo], the HTTP + library [hyper], the source-formatter [rustfmt], and the lint + collection [clippy], tag issues with 'easy' labels for new + contributors. +* Get involved with one of the active Rust-oriented GitHub + organizations, such as [PistonDevelopers], [servo], [redox-os], + [iron], [contain-rs], [hyperium]. It's often easier to find a place + to fit in with these subcommunities, they are in greater need of + help than rust-lang itself, and they are filled with experienced + Rust developers to guide you. +* Help guide libraries from [rust-lang-nursery] into rust-lang proper. + Unfortunately there is not much documentation on what needs to be + done here; ask on [#rust-libs]. +* Inspect the RFC issue tracker for a [requested community + library][requested] and build it. +* Watch [Github Trending][trending] for currently active Rust projects. + +As a library author you will want to be aware of the [best practices +for Rust libraries][lib-prac]. + +Meet other Rust library designers in [#rust-libs]. + + + + +## 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], and +individuals [occassionally blog what they've learned of +rustc][rustc-tour]. 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]. + + + + +[#cargo]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc +[#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 +[#rust-docs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-docs +[#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 +[#rust-tools]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-tools +[#rustc]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc +[/r/rust]: https://reddit.com/r/rust +[@mentioning]: https://github.com/blog/821 +[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-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-docs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs +[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-rustdoc]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc +[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 +[CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md +[Cargo]: https://github.com/rust-lang/cargo/issues +[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 +[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 +[PR]: https://github.com/rust-lang/rust/pulls +[PistonDevelopers]: https://github.com/PistonDevelopers +[Rust By Example]: https://github.com/rust-lang/rust-by-example +[Rust DXR]: https://dxr.mozilla.org/rust/source/src +[Rust Design Patterns]: https://github.com/nrc/patterns +[Rust Style Guidelines]: http://doc.rust-lang.org/style/index.html +[Servo]: https://github.com/servo/servo +[Stack Overflow]: http://stackoverflow.com/questions/tagged/rust +[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 +[This Week in Rust]: http://www.this-week-in-rust.org +[awesome-rust]: https://github.com/kud1ing/awesome-rust +[awesome-rust]: https://github.com/kud1ing/awesome-rust +[book_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book +[bugs]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports +[clippy]: https://github.com/Manishearth/rust-clippy +[coc]: https://www.rust-lang.org/conduct.html +[community team]: https://www.rust-lang.org/team.html#Community +[contain-rs]: https://github.com/contain-rs +[crate_docs]: https://users.rust-lang.org/t/lets-talk-about-ecosystem-documentation/2791 +[dev_proc]: community.html#rust-development +[devs]: https://github.com/rust-lang/rust/blob/master/AUTHORS.txt +[err-issue]: https://github.com/rust-lang/rust/issues/24407 +[err]: http://doc.rust-lang.org/error-index.html +[events]: https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com +[helpful]: http://blogs.msmvps.com/jonskeet/2009/02/17/answering-technical-questions-helpfully/ +[hyper]: https://github.com/hyperium/hyper +[hyperium]: https://github.com/hyperium +[ice]: https://users.rust-lang.org/t/glacier-a-big-ol-pile-of-ice/3380 +[ides]: ides.html +[internals-docs]: http://manishearth.github.com/rust-internals-docs +[internals.rust-lang.org]: https://internals.rust-lang.org/ +[iron]: https://github.com/iron +[issue tracker]: https://github.com/rust-lang/rust/issues +[issue-fcp]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AB-unstable+label%3Afinal-comment-period +[lib-prac]: https://pascalhertleif.de/artikel/good-practices-for-writing-rust-libraries/ +[libs.rs]: http://www.libs.rs +[lru_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc +[main_repo]: https://github.com/rust-lang +[mentor]: https://users.rust-lang.org/t/mentoring-newcomers-to-the-rust-ecosystem/3088 +[mir]: https://github.com/rust-lang/rust/issues/27840 +[pull]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#pull-requests +[redox-os]: https://github.com/redox-os +[requested]: https://github.com/rust-lang/rfcs/labels/A-community-library +[reviews]: http://blog.originate.com/blog/2014/09/29/effective-code-reviews/ +[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 +[rust-lang-nursery]: https://github.com/rust-lang-nursery +[rust-lang/rust]: https://github.com/rust-lang/rust +[rust-lang]: https://github.com/rust-lang +[rust-learning]: https://github.com/ctjhoa/rust-learning +[rust-rosetta]: https://github.com/Hoverbear/rust-rosetta +[rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md +[rustc-perf]: http://ncameron.org/perf-rustc/ +[rustc-tour]: http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/ +[rustfmt]: https://github.com/nrc/rustfmt +[src/doc]: https://github.com/rust-lang/rust/tree/master/src/doc +[std]: http://doc.rust-lang.org/std/index.html +[team]: team.html +[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md +[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 +[trending]: https://github.com/trending?l=rust +[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage +[user groups]: user_groups.html +[users.rust-lang.org]: https://users.rust-lang.org + diff --git a/contributions.md b/contributions.md deleted file mode 100644 index 410b20c0b..000000000 --- a/contributions.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -layout: default -title: How To Contribute ---- - -# Contributing to Rust - -If you're learning Rust, you've no doubt been amazed at how awesome -the language is and will be keen to write more Rust code. Hopefully, -you'll also want to make a meaningful contribution to the community. -If you're not sure how best to do that, then this page will -help. - -**Just want to report a bug in Rust?** [Follow the Rust bug reporting -guide][bugs]. Thanks in advance! - -[bugs]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports - -Rust is an expansive system of projects, some officially maintained -within the [rust-lang] organization on GitHub, but with many -increasingly-important efforts driven from without by its enthusiastic -community. Newcomers will be interested in [an overview of the -organization, processes, and policies of The Rust Project][dev_proc] -and the project's [CONTRIBUTING.md] file, which explains the specifics -of contributing to [rust-lang/rust]. - -There are many ways to contribute to the success of Rust: filing, -triaging and fixing bugs; writing documentation and tests; partipating -in the the design of the language and standard libraries through the -RFC process; improving compile-time and run-time performance; -spreading the tendrils of the Rust community ever-outward. - -This guide focuses on a few avenues for the new contributor: - -* [Bugs, triage, and maintenance](#bugs). Finding issues to fix, - triaging, adding test cases. -* [Documentation](#doc). Not just official documentation, but also - for crates, blog posts, and other unofficial sources. -* [Community building](#comm). Expanding the reach of Rust, and - maintaining its excellence. -* [Tooling, IDEs, and infrastructure](#tool). The hard work of making - Rust accessible to programmers of all kinds. -* [Language and compiler](#comp). Language design, feature - implementation, performance improvement. -* [Libraries](#lib). Including the standard library, but also the - equally-important unofficial crates that make Rust usable. - -As a reminder, all contributors are expected to -follow our [Code of Conduct][coc]. - -[dev_proc]: dev_process.html -[rust-lang]: https://github.com/rust-lang -[rust-lang/rust]: https://github.com/rust-lang/rust -[CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md -[coc]: https://www.rust-lang.org/conduct.html - - -## Bugs, triage, and maintenance - -The day-to-day maintenance of the project revolves around Rust's -[issue tracker] and [pull requests], and more help is always -needed. - -The most basic way to get started contributing to Rust is to look for -the [E-easy][e_easy_issues] or [E-mentor][e_mentor_issues] -labels. These are meant to be approachable for new Rust programmers. - -Rust is always in need of people to [triage] issues: reproduce bugs, -minimize test cases, apply labels. - -Sometimes, an issue will stay open, even though the bug has been -fixed. And sometimes, the original bug may go stale because something -has changed in the meantime. It can be helpful to go through older bug -reports and make sure that they are still valid. Load up an older -issue, double check that it's still true, and leave a comment letting -us know if it is or is not. The [least recently updated][lru_issues] -sort is good for finding issues like this. - -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 begin -to understand a new project and get started contributing. For those -especially interested in testing, there are usually *entirely new -classes* of tests that need to be implemented, and asking #rust-internals -what needs to be tested can be fruitful. - -Once you've found your way around the project and have created a few -pull requests in a particular area of the project, consider actively -reviewing others' pull requests: reviewership is a rare skill and good -reviewers are always appreciated. - -[lru_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc -[issue tracker]: https://github.com/rust-lang/rust/issues -[pull requests]: https://github.com/rust-lang/rust/pulls -[e_easy_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy -[e_mentor_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor -[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage -[E-needstest]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-needstest -[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md - - -## Documentation - -Documentation is never good enough and there's never enough of it. -Writing docs is a really valuable way to contribute to open source -projects. Many aspects of the docs don't require super-deep knowledge, -especially if they're aimed at newcomers. It's also a great way to -learn more about the language or specific libraries. - -- [The Book][rustbook_issues] The main guide to learning Rust. -- [Rust Documentation][rustdoc_issues] -- [Rust by Example][rust_by_example_issues] -- [Rust for C++ Programmers][rust_for_cpp_issues] A tutorial aimed -at experienced C++ programmers coming to Rust. - -[rustbook_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book -[rustdoc_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs -[rust_by_example_issues]: https://github.com/rust-lang/rust-by-example/issues -[rust_for_cpp_issues]: https://github.com/nrc/r4cppp/issues - - - -## Community building - - -## Tooling, IDEs, and infrastructure - -Tools play a huge part in the success of a language. Rust has some -great tool support, in particular with debugging and package -management, but we need much more. - -- [cargo](https://github.com/rust-lang/cargo/issues) Rust's package manager and build system. -- [rustdoc](https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc) - Produces documentation for the official libraries and user projects. -- [racer](https://github.com/phildawes/racer) Code completion. -- [rustfmt](https://github.com/nrc/rustfmt) Code formatting. -- [multirust](https://github.com/brson/multirust/issues) For managing - multiple installations of the Rust toolchain. -- [homu](https://github.com/barosl/homu/issues) Acts as a gatekeeper for commits. - - -## Libraries - -[Libstd][libstd], [libcollections][libcollections], -[liballoc][liballoc] and [libcore][libcore] are the main library -crates. These all appear to users as if they are part of libstd, the -standard library. These tend to be very fundamental libraries - -built-in types, low level IO and concurrency, allocation, essential -collections, and so forth. You should join [#rust-libs][libs_irc] if -you are interested in contributing to the Rust libraries. - -[libstd]: https://github.com/rust-lang/rust/tree/master/src/libstd -[libcollections]: https://github.com/rust-lang/rust/tree/master/src/libcollections -[liballoc]: https://github.com/rust-lang/rust/tree/master/src/liballoc -[libcore]: https://github.com/rust-lang/rust/tree/master/src/libcore -[libs_irc]: irc://moznet/rust-libs - - -## Language and compiler - -The compiler is part of the [main repo][main_repo], which also -includes the standard library crates and a whole bunch of supporting -code. For questions about the compiler, there is the -[#rustc][rustc_irc] IRC channel. Compiler errors (ICE for 'internal -compiler errors') can be searched for in issues using the -[I-ICE][i_ice_issues] label. 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. If you're interested in parsing, macros, -syntactic stuff, the [parsing][parsing_issues] label and the -[macro][macro_issues] label are a good places to start. - -[main_repo]: https://github.com/rust-lang -[rust_irc]: irc://moznet/rustc -[i_ice_issues]: https://github.com/rust-lang/rust/labels/I-ICE -[parsing_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser -[macro_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-parser+label%3AA-macros - -#### Other Contributions - -Try [Github Trending][trending] for currently active Rust projects. -There are a number of other ways to contribute to Rust that don't deal -directly with the Rust repository. - -- Answer questions in [#rust][rust_irc], on the [Rust Forum][forum] or - on [Stack Overflow][stack_overflow]. -- Participate in the [RFC process][rfcs]. -- Find a [requested community library][requested], build it, and - publish it to [Crates.io][crates]. Easier said than done, -but very, very valuable! - -[trending]: https://github.com/trending?l=rust -[rust_irc]: irc://moznet/rust -[forum]: https://users.rust-lang.org/ -[stack_overflow]: http://stackoverflow.com/questions/tagged/rust -[rfcs]: https://github.com/rust-lang/rfcs -[requested]: https://github.com/rust-lang/rfcs/labels/A-community-library -[crates]: http://crates.io From 87c9ee069a99cc42bc8ea7ae4bc1c271ab733100 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Wed, 2 Dec 2015 22:19:04 +0000 Subject: [PATCH 06/10] Link the developers to the github contribution page, not AUTHORS.txt --- contribute.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contribute.md b/contribute.md index 6df1f68a8..b4bd8845d 100644 --- a/contribute.md +++ b/contribute.md @@ -13,7 +13,7 @@ will help. guide][bugs]. Thanks in advance! Rust is an expansive system of projects, the most prominent of which -are maintained by the [The Rust Project Developers][devs] in [the +are maintained by [The Rust Project Developers][devs] in [the rust-lang organization on GitHub][rust-lang]. Newcomers may be interested in [an overview of the organization, processes, and policies of The Rust Project][dev_proc] and the project's @@ -405,7 +405,7 @@ TODO: some of this RFC description could probably go in the RFC readme [contain-rs]: https://github.com/contain-rs [crate_docs]: https://users.rust-lang.org/t/lets-talk-about-ecosystem-documentation/2791 [dev_proc]: community.html#rust-development -[devs]: https://github.com/rust-lang/rust/blob/master/AUTHORS.txt +[devs]: https://github.com/rust-lang/rust/graphs/contributors [err-issue]: https://github.com/rust-lang/rust/issues/24407 [err]: http://doc.rust-lang.org/error-index.html [events]: https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com From 5d372c88a79878bf90259831755cfa223b626bef Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Fri, 4 Dec 2015 22:50:22 +0000 Subject: [PATCH 07/10] Address feedback on contributing page --- contribute.md | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/contribute.md b/contribute.md index b4bd8845d..c8088dd54 100644 --- a/contribute.md +++ b/contribute.md @@ -9,7 +9,7 @@ You've started learning Rust. You love it, and you want to be a part of it. If you're not sure how to get involved, then this page will help. -**Just want to report a bug in Rust?** [Follow the bug reporting +**Found a bug and need to report it?** [Follow the bug reporting guide][bugs]. Thanks in advance! Rust is an expansive system of projects, the most prominent of which @@ -59,10 +59,10 @@ 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 the solving the issue and -[submitting the fix GitHub pull request][pull]. Contact them about the -issue, on the issue tracker by [@mentioning] their name, on IRC, or -through email. Note that Rust developers get a lot of notifications +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! @@ -84,7 +84,7 @@ 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 &emdash; just start constructively and politely +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]. @@ -96,14 +96,13 @@ TODO: @nrc says suggesting everybody review w/o training is bad ## Documentation -Documentation is never good enough and there's never enough of it, -writing documentation is a valuable way to contribute. 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. +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 @@ -288,12 +287,11 @@ Rust to LLVM IR; [A-debuginfo], generation of metadata used by debuggers; 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], and -individuals [occassionally blog what they've learned of -rustc][rustc-tour]. 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 +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. @@ -439,7 +437,6 @@ TODO: some of this RFC description could probably go in the RFC readme [rust-rosetta]: https://github.com/Hoverbear/rust-rosetta [rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md [rustc-perf]: http://ncameron.org/perf-rustc/ -[rustc-tour]: http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/ [rustfmt]: https://github.com/nrc/rustfmt [src/doc]: https://github.com/rust-lang/rust/tree/master/src/doc [std]: http://doc.rust-lang.org/std/index.html From c9c8f02f336a7420af9105c636c540f4008fd121 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Tue, 22 Dec 2015 20:54:29 +0000 Subject: [PATCH 08/10] Add *~ to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 9fb9bbfa1..28f635de7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ _site Gemfile.lock serve/ +*~ \ No newline at end of file From 1bb607f1af91527c9c016a487801eaffc1896013 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Tue, 22 Dec 2015 20:54:38 +0000 Subject: [PATCH 09/10] Break contribution page into subpages --- contribute-bugs.md | 63 ++++++ contribute-community.md | 81 ++++++++ contribute-compiler.md | 109 +++++++++++ contribute-docs.md | 67 +++++++ contribute-libs.md | 66 +++++++ contribute-tools.md | 40 ++++ contribute.md | 416 ++-------------------------------------- 7 files changed, 441 insertions(+), 401 deletions(-) create mode 100644 contribute-bugs.md create mode 100644 contribute-community.md create mode 100644 contribute-compiler.md create mode 100644 contribute-docs.md create mode 100644 contribute-libs.md create mode 100644 contribute-tools.md diff --git a/contribute-bugs.md b/contribute-bugs.md new file mode 100644 index 000000000..b9b79a0ac --- /dev/null +++ b/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]. + + + +[@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 diff --git a/contribute-community.md b/contribute-community.md new file mode 100644 index 000000000..4c9e7d861 --- /dev/null +++ b/contribute-community.md @@ -0,0 +1,81 @@ +--- +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***. + +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]. + + + +[#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/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com +[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 +[user groups]: user_groups.html +[users.rust-lang.org]: https://users.rust-lang.org diff --git a/contribute-compiler.md b/contribute-compiler.md new file mode 100644 index 000000000..775ccd698 --- /dev/null +++ b/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]. + + + + +[#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 diff --git a/contribute-docs.md b/contribute-docs.md new file mode 100644 index 000000000..7a6b8ef24 --- /dev/null +++ b/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]. + + + +[#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 diff --git a/contribute-libs.md b/contribute-libs.md new file mode 100644 index 000000000..ebeaa6f66 --- /dev/null +++ b/contribute-libs.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Contributing to Rust — libraries · The Rust Programming Language +--- + +# Contributing to Rust — libraries + +If you want to contribute to Rust by writing volumes of Rust code, +then libraries are where it's at: since Rust is a young language, +there are many types of libraries that either do not exist yet +or are incomplete and in need of improvement or competition. + +Deciding what to write that will have impact and be fun is a common +difficulty. Here are some ideas: + +* Read and participate in the weekly "what's everyone working on + this week" threads on [/r/rust] and [users.rust-lang.org]. These are + packed with exciting announcements from other Rust programmers in + need of collaborators. +* Familiarize yourself with the best Rust libraries through + [awesome-rust] and [libs.rs]. +* Some larger projects, including the web browser [Servo], the HTTP + library [hyper], the source-formatter [rustfmt], and the lint + collection [clippy], tag issues with 'easy' labels for new + contributors. +* Get involved with one of the active Rust-oriented GitHub + organizations, such as [PistonDevelopers], [servo], [redox-os], + [iron], [contain-rs], [hyperium]. It's often easier to find a place + to fit in with these subcommunities, they are in greater need of + help than rust-lang itself, and they are filled with experienced + Rust developers to guide you. +* Help guide libraries from [rust-lang-nursery] into rust-lang proper. + Unfortunately there is not much documentation on what needs to be + done here; ask on [#rust-libs]. +* Inspect the RFC issue tracker for a [requested community + library][requested] and build it. +* Watch [Github Trending][trending] for currently active Rust projects. + +As a library author you will want to be aware of the [best practices +for Rust libraries][lib-prac]. + +Meet other Rust library designers in [#rust-libs]. + + + +[#rust-libs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-libs +[/r/rust]: https://reddit.com/r/rust +[PistonDevelopers]: https://github.com/PistonDevelopers +[Servo]: https://github.com/servo/servo +[Servo]: https://github.com/servo/servo +[awesome-rust]: https://github.com/kud1ing/awesome-rust +[clippy]: https://github.com/Manishearth/rust-clippy +[contain-rs]: https://github.com/contain-rs +[hyper]: https://github.com/hyperium/hyper +[hyperium]: https://github.com/hyperium +[iron]: https://github.com/iron +[lib-prac]: https://pascalhertleif.de/artikel/good-practices-for-writing-rust-libraries/ +[libs.rs]: http://www.libs.rs +[redox-os]: https://github.com/redox-os +[requested]: https://github.com/rust-lang/rfcs/labels/A-community-library +[rust-lang-nursery]: https://github.com/rust-lang-nursery +[rustfmt]: https://github.com/nrc/rustfmt +[trending]: https://github.com/trending?l=rust +[users.rust-lang.org]: https://users.rust-lang.org diff --git a/contribute-tools.md b/contribute-tools.md new file mode 100644 index 000000000..911c532ec --- /dev/null +++ b/contribute-tools.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Contributing to Rust — tooling, IDEs and infrastructure · The Rust Programming Language +--- + +# Contributing to Rust — tooling, IDEs and infrastructure + +Tools play a huge part in the success of a language, and there is a +great deal left to implement. ***A major focus of Rust development now +is [improving the IDE experience][ides]***. This involves work +throughout the Rust stack, from the compiler itself through your +favorite IDE. Follow the link for more information. + +Both Cargo, the Rust package manager, and rustdoc, +the Rust documentation generator, while full-featured and functional, +suffer from a lack of developers. Rustdoc has many open issues, under +the main repository's [A-rustdoc] label. They are mostly bugs and +contributing is a matter of fixing the bug and submitting a pull +request. Cargo has [its own repository and issues][Cargo], and those +interested in contributing might want to introduce themselves in +[#cargo]. + +Although Rust can be run under both the gdb and lldb debuggers with +limited success, there are still many cases where debugging does not +work as expected. The [A-debuginfo] issue tracks these. + +For ideas for more tooling projects to contributo to see +[awesome-rust]. + +There are often other tooling projects of interest just waiting for +the right people to come along and implement them. Discuss with other +Rust tooling enthusiasts in [#rust-tools]. + +[#cargo]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc +[#rust-tools]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-tools +[A-debuginfo]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-debuginfo +[A-rustdoc]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc +[Cargo]: https://github.com/rust-lang/cargo/issues +[awesome-rust]: https://github.com/kud1ing/awesome-rust +[ides]: ides.html diff --git a/contribute.md b/contribute.md index c8088dd54..c985184b8 100644 --- a/contribute.md +++ b/contribute.md @@ -23,17 +23,21 @@ to [rust-lang/rust]. There are many ways to contribute to the success of Rust. This guide focuses on a few avenues for the new contributor: -* [Finding, triaging and fixing issues](#bugs). The basic work - of maintaining a large and active project like Rust. -* [Documentation](#docs). Not just official documentation, but also - for crates, blog posts, and other unofficial sources. -* [Community building](#community). Helping your fellow Rustacean, - and expanding the reach of Rust. -* [Tooling, IDEs and infrastructure](#tools). There's so much - to do here. -* [Libraries](#libs). Rust's suitability for any particular task - is mostly dependent on the quality libraries that exist. -* [Language, compiler and the standard library](#compiler). Language design, feature implementation, performance improvement. +* [Finding, triaging and fixing issues](contribute-bugs.html). The + basic work of maintaining a large and active project like Rust. +* [Documentation](contribute-docs.html). Not just official + documentation, but also for crates, blog posts, and other unofficial + sources. +* [Community building](contribute-community.html). Helping your fellow + Rustacean, and expanding the reach of Rust. +* [Tooling, IDEs and infrastructure](contribute-tools.html). The + important pieces that make using a language practical and painless. +* [Libraries](contribute-libs.html). Rust's suitability for any + particular task is mostly dependent on availability of quality + libraries. +* [Language, compiler and the standard + library](contribute-compiler.html). Language design, feature + implementation, performance improvement. If you need additional guidance ask on [#rust-internals] or [internals.rust-lang.org]. @@ -49,403 +53,13 @@ TODO: Write guide to advertising Rust projects to link from libs / community building --> - -## 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]. - - - - -## 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][book_issues] 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]. - - - - -## 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***. - -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]. - - - - -## Tooling, IDEs, and infrastructure - -Tools play a huge part in the success of a language, and there is a -great deal left to implement. ***A major focus of Rust development now -is [improving the IDE experience][ides]***. This involves work -throughout the Rust stack, from the compiler itself through your -favorite IDE. Follow the link for more information. - -Both Cargo, the Rust package manager, and rustdoc, -the Rust documentation generator, while full-featured and functional, -suffer from a lack of developers. Rustdoc has many open issues, under -the main repository's [A-rustdoc] label. They are mostly bugs and -contributing is a matter of fixing the bug and submitting a pull -request. Cargo has [its own repository and issues][Cargo], and those -interested in contributing might want to introduce themselves in -[#cargo]. - -Although Rust can be run under both the gdb and lldb debuggers with -limited success, there are still many cases where debugging does not -work as expected. The [A-debuginfo] issue tracks these. - -For ideas for more tooling projects to contributo to see -[awesome-rust]. - -There are often other tooling projects of interest just waiting for -the right people to come along and implement them. Discuss with other -Rust tooling enthusiasts in [#rust-tools]. - - -## Libraries - -If you want to contribute to Rust by writing volumes of Rust code, -then libraries are where it's at: since Rust is a young language, -there are many types of libraries that either do not exist yet -or are incomplete and in need of improvement or competition. - -Deciding what to write that will have impact and be fun is a common -difficulty. Here are some ideas: - -* Read and participate in the weekly "what's everyone working on - this week" threads on [/r/rust] and [users.rust-lang.org]. These are - packed with exciting announcements from other Rust programmers in - need of collaborators. -* Familiarize yourself with the best Rust libraries through - [awesome-rust] and [libs.rs]. -* Some larger projects, including the web browser [Servo], the HTTP - library [hyper], the source-formatter [rustfmt], and the lint - collection [clippy], tag issues with 'easy' labels for new - contributors. -* Get involved with one of the active Rust-oriented GitHub - organizations, such as [PistonDevelopers], [servo], [redox-os], - [iron], [contain-rs], [hyperium]. It's often easier to find a place - to fit in with these subcommunities, they are in greater need of - help than rust-lang itself, and they are filled with experienced - Rust developers to guide you. -* Help guide libraries from [rust-lang-nursery] into rust-lang proper. - Unfortunately there is not much documentation on what needs to be - done here; ask on [#rust-libs]. -* Inspect the RFC issue tracker for a [requested community - library][requested] and build it. -* Watch [Github Trending][trending] for currently active Rust projects. - -As a library author you will want to be aware of the [best practices -for Rust libraries][lib-prac]. - -Meet other Rust library designers in [#rust-libs]. - - - - -## 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]. - - - - -[#cargo]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc -[#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 -[#rust-docs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-docs [#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 -[#rust-tools]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-tools -[#rustc]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc -[/r/rust]: https://reddit.com/r/rust -[@mentioning]: https://github.com/blog/821 -[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-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-docs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs -[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-rustdoc]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc -[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 [CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md -[Cargo]: https://github.com/rust-lang/cargo/issues -[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 -[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 -[PR]: https://github.com/rust-lang/rust/pulls -[PistonDevelopers]: https://github.com/PistonDevelopers -[Rust By Example]: https://github.com/rust-lang/rust-by-example -[Rust DXR]: https://dxr.mozilla.org/rust/source/src -[Rust Design Patterns]: https://github.com/nrc/patterns -[Rust Style Guidelines]: http://doc.rust-lang.org/style/index.html -[Servo]: https://github.com/servo/servo -[Stack Overflow]: http://stackoverflow.com/questions/tagged/rust -[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 -[This Week in Rust]: http://www.this-week-in-rust.org -[awesome-rust]: https://github.com/kud1ing/awesome-rust -[awesome-rust]: https://github.com/kud1ing/awesome-rust -[book_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book [bugs]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports -[clippy]: https://github.com/Manishearth/rust-clippy [coc]: https://www.rust-lang.org/conduct.html [community team]: https://www.rust-lang.org/team.html#Community -[contain-rs]: https://github.com/contain-rs -[crate_docs]: https://users.rust-lang.org/t/lets-talk-about-ecosystem-documentation/2791 [dev_proc]: community.html#rust-development [devs]: https://github.com/rust-lang/rust/graphs/contributors -[err-issue]: https://github.com/rust-lang/rust/issues/24407 -[err]: http://doc.rust-lang.org/error-index.html -[events]: https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com -[helpful]: http://blogs.msmvps.com/jonskeet/2009/02/17/answering-technical-questions-helpfully/ -[hyper]: https://github.com/hyperium/hyper -[hyperium]: https://github.com/hyperium -[ice]: https://users.rust-lang.org/t/glacier-a-big-ol-pile-of-ice/3380 -[ides]: ides.html -[internals-docs]: http://manishearth.github.com/rust-internals-docs [internals.rust-lang.org]: https://internals.rust-lang.org/ -[iron]: https://github.com/iron -[issue tracker]: https://github.com/rust-lang/rust/issues -[issue-fcp]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AB-unstable+label%3Afinal-comment-period -[lib-prac]: https://pascalhertleif.de/artikel/good-practices-for-writing-rust-libraries/ -[libs.rs]: http://www.libs.rs -[lru_issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc -[main_repo]: https://github.com/rust-lang -[mentor]: https://users.rust-lang.org/t/mentoring-newcomers-to-the-rust-ecosystem/3088 -[mir]: https://github.com/rust-lang/rust/issues/27840 -[pull]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#pull-requests -[redox-os]: https://github.com/redox-os -[requested]: https://github.com/rust-lang/rfcs/labels/A-community-library -[reviews]: http://blog.originate.com/blog/2014/09/29/effective-code-reviews/ -[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 -[rust-lang-nursery]: https://github.com/rust-lang-nursery [rust-lang/rust]: https://github.com/rust-lang/rust [rust-lang]: https://github.com/rust-lang -[rust-learning]: https://github.com/ctjhoa/rust-learning -[rust-rosetta]: https://github.com/Hoverbear/rust-rosetta -[rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md -[rustc-perf]: http://ncameron.org/perf-rustc/ -[rustfmt]: https://github.com/nrc/rustfmt -[src/doc]: https://github.com/rust-lang/rust/tree/master/src/doc -[std]: http://doc.rust-lang.org/std/index.html -[team]: team.html -[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md -[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 -[trending]: https://github.com/trending?l=rust -[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage -[user groups]: user_groups.html -[users.rust-lang.org]: https://users.rust-lang.org - From 79f1c1f53b795ee7d58820d6a5824ea5ec22a53c Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Mon, 4 Jan 2016 19:01:50 +0000 Subject: [PATCH 10/10] Few tweaks Add link to Manish's new blog post on mentorship. Bolden the contributing subpage links. Remove governance link that goes nowhere. --- contribute-community.md | 5 ++++- contribute.md | 22 ++++++++++------------ 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/contribute-community.md b/contribute-community.md index 4c9e7d861..e4c38ec55 100644 --- a/contribute-community.md +++ b/contribute-community.md @@ -34,7 +34,9 @@ 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***. +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], @@ -77,5 +79,6 @@ Conduct training on Rust. (link to training material). [events]: https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com [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 diff --git a/contribute.md b/contribute.md index c985184b8..71f5725e9 100644 --- a/contribute.md +++ b/contribute.md @@ -15,28 +15,26 @@ guide][bugs]. Thanks in advance! Rust is an expansive system of projects, the most prominent of which are maintained by [The Rust Project Developers][devs] in [the rust-lang organization on GitHub][rust-lang]. Newcomers may be -interested in [an overview of the organization, processes, and -policies of The Rust Project][dev_proc] and the project's -[CONTRIBUTING.md] file, which explains the specifics of contributing -to [rust-lang/rust]. +interested in the project's [CONTRIBUTING.md] file, which explains the +mechanics of contributing to [rust-lang/rust]. There are many ways to contribute to the success of Rust. This guide focuses on a few avenues for the new contributor: -* [Finding, triaging and fixing issues](contribute-bugs.html). The +* [**Finding, triaging and fixing issues**](contribute-bugs.html). The basic work of maintaining a large and active project like Rust. -* [Documentation](contribute-docs.html). Not just official +* [**Documentation**](contribute-docs.html). Not just official documentation, but also for crates, blog posts, and other unofficial sources. -* [Community building](contribute-community.html). Helping your fellow +* [**Community building**](contribute-community.html). Helping your fellow Rustacean, and expanding the reach of Rust. -* [Tooling, IDEs and infrastructure](contribute-tools.html). The +* [**Tooling, IDEs and infrastructure**](contribute-tools.html). The important pieces that make using a language practical and painless. -* [Libraries](contribute-libs.html). Rust's suitability for any +* [**Libraries**](contribute-libs.html). Rust's suitability for any particular task is mostly dependent on availability of quality libraries. -* [Language, compiler and the standard - library](contribute-compiler.html). Language design, feature +* [**Language, compiler and the standard + library**](contribute-compiler.html). Language design, feature implementation, performance improvement. If you need additional guidance ask on [#rust-internals] or @@ -47,7 +45,7 @@ contributors are expected to follow our [Code of Conduct][coc]. If you have questions about this please inquire with the [community team].