From 6a1daff55a74b7ffa29fb020cd4831b38e7ef970 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 8 Apr 2023 12:20:01 -0400 Subject: [PATCH 1/6] Move "Getting Started" to the first page This page is better suited for people landing immediately from CONTRIBUTING.md, or who haven't heard of the guide before. "About This Guide" is still useful, but doesn't need to be the very first page. --- src/SUMMARY.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7c85576ff..b01cb6797 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,8 +1,7 @@ # Summary -[About this guide](./about-this-guide.md) - [Getting Started](./getting-started.md) +[About this guide](./about-this-guide.md) --- From daf9095380587b8ad940af4787896881e00dbdf4 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 8 Apr 2023 12:21:07 -0400 Subject: [PATCH 2/6] Fix link; remove duplicate link --- src/about-this-guide.md | 5 ++--- src/contributing.md | 2 ++ 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/about-this-guide.md b/src/about-this-guide.md index 8fc2cd6d7..944ebf5a8 100644 --- a/src/about-this-guide.md +++ b/src/about-this-guide.md @@ -60,13 +60,12 @@ You might also find the following sites useful: - This guide contains information about how various parts of the compiler work and how to contribute to the compiler. -- [rustc API docs] -- rustdoc documentation for the compiler +- [rustc API docs] -- rustdoc documentation for the compiler, devtools, and internal tools - [Forge] -- contains documentation about Rust infrastructure, team procedures, and more - [compiler-team] -- the home-base for the Rust compiler team, with description of the team procedures, active working groups, and the team calendar. - [std-dev-guide] -- a similar guide for developing the standard library. - [The t-compiler zulip][z] -- [The compiler's documentation (rustdocs)](https://doc.rust-lang.org/nightly/nightly-rustc/) - [The Forge](https://forge.rust-lang.org/) has more documentation about various procedures. - `#contribute` and `#wg-rustup` on [Discord](https://discord.gg/rust-lang). - The [Rust Internals forum][rif], a place to ask questions and @@ -102,7 +101,7 @@ You might also find the following sites useful: [Miri]: https://github.com/rust-lang/miri [@bors]: https://github.com/bors [GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/ -[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ +[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle [Forge]: https://forge.rust-lang.org/ [compiler-team]: https://github.com/rust-lang/compiler-team/ [std-dev-guide]: https://std-dev-guide.rust-lang.org/ diff --git a/src/contributing.md b/src/contributing.md index 549c18cc4..3be66a691 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -189,6 +189,8 @@ a pull request, CI builds the compiler and tests it against the [compiler test suite][rctd], and also performs other tests such as checking that your pull request is in compliance with Rust's style guidelines. +[rctd]: tests/intro.md + Running continuous integration tests allows PR authors to catch mistakes early without going through a first review cycle, and also helps reviewers stay aware of the status of a particular pull request. From 280cadcd09072fbb1f52744efd95ddf5137269ae Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 8 Apr 2023 12:21:32 -0400 Subject: [PATCH 3/6] Make the "Asking Questions" section more useful - Update outdated chat platforms - Link to the community page - Suggest `git shortlog` for finding experts --- src/getting-started.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 87a5dbbd5..101347788 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -21,8 +21,12 @@ chapter on how to build and run the compiler](./building/how-to-build-and-run.md ## Asking Questions -If you have questions, please make a post on [internals.rust-lang.org][internals] or -hop on the [Rust Discord server][rust-discord] or [Rust Zulip server][rust-zulip]. +If you have questions, please make a post on the [Rust Zulip server][rust-zulip] or +[internals.rust-lang.org][internals]. If you are contributing to Rustup, be aware they are not on +Zulip - you can ask questions in `#wg-rustup` [on Discord][rust-discord]. +See [the Community page][community] on the official website for more resources. + +[community]: https://www.rust-lang.org/community As a reminder, all contributors are expected to follow our [Code of Conduct][coc]. @@ -48,6 +52,12 @@ compiler, [consult this "experts map"][map]. It's not perfectly complete, though, so please also feel free to ask questions even if you can't figure out who to ping. +Another way to find experts for a given part of the compiler is to see who has made recent commits. +For example, to find people who have recently worked on name resolution since the 1.68.2 release, +you could run `git shortlog -n 1.68.2.. compiler/rustc_resolve/`. Ignore any commits starting with +"Rollup merge" or commits by `@bors` (see [CI contribution prodcedures](./contributing.md#ci) for +more information about these commits). + [map]: https://github.com/rust-lang/compiler-team/blob/master/content/experts/map.toml ### Etiquette From 71e1652995df3659a7beddf9a6318749907d4238 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 8 Apr 2023 12:22:32 -0400 Subject: [PATCH 4/6] Add a "What should I work on?" section This is the first question I get from nearly all contributors. So far I've been giving links to individual issues, but they quickly go out of date or get fixed, and then I have more work to do to help people find an issue. Add some suggestions for work people can find themselves, without having to first consult an expert. This also moves the "Cloning and Building" stub to the bottom of the page. --- src/contributing.md | 3 -- src/getting-started.md | 63 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 57 insertions(+), 9 deletions(-) diff --git a/src/contributing.md b/src/contributing.md index 3be66a691..34691acaa 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -375,12 +375,9 @@ 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 sort][lru] is good for finding issues like this. -If you're looking for somewhere to start, check out the [E-easy] tag. - [Thanks to `@rustbot`][rustbot], anyone can help triage issues by adding appropriate labels to issues that haven't been triaged yet: -[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc [rustbot]: ./rustbot.md diff --git a/src/getting-started.md b/src/getting-started.md index 101347788..919b2415f 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -70,20 +70,67 @@ Just pinging someone without providing any context can be a bit annoying and just create noise, so we ask that you be mindful of the fact that the `t-compiler` folks get a lot of pings in a day. -## Cloning and Building +## What should I work on? -See ["How to build and run the compiler"](./building//how-to-build-and-run.md). +The Rust project is quite large and it can be difficult to know which parts of the project need +help, or are a good starting place for beginners. Here are some suggested starting places. + +### Easy or mentored issues + +If you're looking for somewhere to start, check out the following [issue +search][help-wanted-search]. See the [Triage] for an explanation of these labels. You can also try +filtering the search to areas you're interested in. For example: + +- `repo:rust-lang/rust-clippy` will only show clippy issues +- `label:T-compiler` will only show issues related to the compiler +- `label:A-diagnostics` will only show diagnostic issues + +Not all important or beginner work has issue labels. +See below for how to find work that isn't labelled. + +[help-wanted-search]: https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Arust-lang+no%3Aassignee+label%3AE-easy%2C%22good+first+issue%22%2Cgood-first-issue%2CE-medium%2CE-help-wanted%2CE-mentor +[Triage]: ./contributing.md#issue-triage + +### Recurring work + +Some work is too large to be done by a single person. In this case, it's commmon to have "Tracking +issues" to co-ordinate the work between contributors. Here are some example tracking issues where +it's easy to pick up a work without a large time commitment: + +- [Rustdoc Askama Migration](https://github.com/rust-lang/rust/issues/108868) +- [Diagnostic Translation](https://github.com/rust-lang/rust/issues/100717) +- [Move UI tests to subdirectories](https://github.com/rust-lang/rust/issues/73494) + +If you find more recurring work, please feel free to add it here! -## Contributing code to other Rust projects +### Clippy issues + +The [Clippy] project has spent a long time making its contribution process as friendly to newcomers +as possible. Consider working on it first to get familiar with the process and the compiler +internals. + +See [the Clippy contribution guide][clippy-contributing] for instructions on getting started. + +[Clippy]: https://doc.rust-lang.org/clippy/ +[clippy-contributing]: https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md + +### Diagnostic issues + +Many diagnostic issues are self-contained and don't need detailed background knowledge of the +compiler. You can see a list of diagnostic issues [here][diagnostic-issues]. + +[diagnostic-issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AA-diagnostics+no%3Aassignee + +### Contributing code to other Rust projects There are a bunch of other projects that you can contribute to outside of the -`rust-lang/rust` repo, including `clippy`, `miri`, `chalk`, and many others. +`rust-lang/rust` repo, including `cargo`, `miri`, `rustup`, and many others. These repos might have their own contributing guidelines and procedures. Many of them are owned by working groups (e.g. `chalk` is largely owned by WG-traits). For more info, see the documentation in those repos' READMEs. -## Other ways to contribute +### Other ways to contribute There are a bunch of other ways you can contribute, especially if you don't feel comfortable jumping straight into the large `rust-lang/rust` codebase. @@ -118,9 +165,13 @@ incredibly helpful: [wg]: https://rust-lang.github.io/compiler-team/working-groups/ [triage]: ./contributing.md#issue-triage +## Cloning and Building + +See ["How to build and run the compiler"](./building//how-to-build-and-run.md). + ## Contributor Procedures -This section has moved to the ["Contribution Procedures"](./contributing.md) chapter. +This section has moved to the ["Contribution Procedures"](./contributing.mD) chapter. ## Other Resources From 202dca059eedfb619286d311b4c14bbe9da3f9d4 Mon Sep 17 00:00:00 2001 From: jyn Date: Sat, 8 Apr 2023 22:36:35 -0500 Subject: [PATCH 5/6] Apply suggestions from code review Thank you JohnTitor for finding these! Co-authored-by: Yuki Okushi --- src/getting-started.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/getting-started.md b/src/getting-started.md index 919b2415f..e5be518d7 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -93,9 +93,9 @@ See below for how to find work that isn't labelled. ### Recurring work -Some work is too large to be done by a single person. In this case, it's commmon to have "Tracking -issues" to co-ordinate the work between contributors. Here are some example tracking issues where -it's easy to pick up a work without a large time commitment: +Some work is too large to be done by a single person. In this case, it's common to have "Tracking +issues" to co-ordinate the work between contributors. Here are some example tracking issues where +it's easy to pick up work without a large time commitment: - [Rustdoc Askama Migration](https://github.com/rust-lang/rust/issues/108868) - [Diagnostic Translation](https://github.com/rust-lang/rust/issues/100717) @@ -106,7 +106,7 @@ If you find more recurring work, please feel free to add it here! ### Clippy issues The [Clippy] project has spent a long time making its contribution process as friendly to newcomers -as possible. Consider working on it first to get familiar with the process and the compiler +as possible. Consider working on it first to get familiar with the process and the compiler internals. See [the Clippy contribution guide][clippy-contributing] for instructions on getting started. @@ -171,7 +171,7 @@ See ["How to build and run the compiler"](./building//how-to-build-and-run.md). ## Contributor Procedures -This section has moved to the ["Contribution Procedures"](./contributing.mD) chapter. +This section has moved to the ["Contribution Procedures"](./contributing.md) chapter. ## Other Resources From a0376d582394080c0de32d123347397e5ab7db52 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 8 Apr 2023 22:38:27 -0500 Subject: [PATCH 6/6] Link to governance page It has links to the specific channel/stream for each team. --- src/getting-started.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/getting-started.md b/src/getting-started.md index e5be518d7..d5c948994 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -24,8 +24,10 @@ chapter on how to build and run the compiler](./building/how-to-build-and-run.md If you have questions, please make a post on the [Rust Zulip server][rust-zulip] or [internals.rust-lang.org][internals]. If you are contributing to Rustup, be aware they are not on Zulip - you can ask questions in `#wg-rustup` [on Discord][rust-discord]. -See [the Community page][community] on the official website for more resources. +See the [list of teams and working groups][governance] and [the Community page][community] on the +official website for more resources. +[governance]: https://www.rust-lang.org/governance [community]: https://www.rust-lang.org/community As a reminder, all contributors are expected to follow our [Code of Conduct][coc].