Reorganize "Getting Started" and add a "What should I work on?" section #1665

jyn514 · 2023-04-08T16:29:56Z

"What should I work on?" 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.

Move "Getting Started" to be the first page of the guide
Fix up some links
Make the "Asking Questions" section more useful
Move the "Cloning and Building" stub to the bottom of the
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/getting-started.md

src/about-this-guide.md

tshepang · 2023-04-09T19:41:46Z

src/about-this-guide.md

@@ -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/


this does not point to the right place... it includes other crates in rust-lang/rust, like cargo

Hmm. This is a rustdoc limitation, we pass it all unstable crates at once. I can change it back to pointing directly at rustc_middle, but the sidebar will still show all the crates:

what do you suggest

I think we should link to the index page, but expand the link description a bit to make it clear this includes more crates than just rustc.

A curious thing is that my local docs (pointing to rustc_middle docs, and built with x doc library compiler --stage 1) only shows rustc crates actually (with the exception of coverage_test_macros), unlike the hosted docs.

You've explicitly specified x doc library compiler. To replicate CI you need ./configure --set compiler-docs && x doc without any filter, which will also build docs for cargo/rustdoc/miri/rustfmt.

heh, indeed

One other thing is that rustc_middle is said to be the "main crate" of rustc... do you think this is still accurate, and if so, would it be okay to point to it as the landing page for "rustc docs"?

I would rather not block this change on the link, I don't feel strongly about it. I'll revert the change to "About this guide".

I agree... the discussion should happen elsewhere. Such is why I am a fan of PRs avoiding drive-by changes.

- Update outdated chat platforms - Link to the community page - Suggest `git shortlog` for finding experts

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.

Thank you JohnTitor for finding these! Co-authored-by: Yuki Okushi <jtitor@2k36.org>

It has links to the specific channel/stream for each team.

Update books ## rust-lang/book 1 commits in 0510ca84c2ce6bf93c4ccf9248756e9e4fd00b12..c06006157b14b3d47b5c716fc392b77f3b2e21ce 2023-04-03 15:31:55 UTC to 2023-04-03 15:31:55 UTC - Fix grammar (rust-lang/book#3600) ## rust-lang/reference 3 commits in 3c47807a3131b3c7cacb508f52632078d253cd0a..1f8dc727e94ae4ef92adf70df979521a1ea1143e 2023-04-09 14:04:53 UTC to 2023-03-29 13:21:47 UTC - Explain typos in `asm!` can be unsound (rust-lang/reference#1344) - Fix coding style in example: add space between module name and bracket (rust-lang/reference#1347) - redundant word removed (rust-lang/reference#1346) ## rust-lang/rust-by-example 1 commits in ba84bf35d0f17d404003349309201654d25f61af..31961fe22521a779070a44a8f30a2b00a20b6212 2023-04-10 13:06:34 UTC to 2023-04-10 13:06:34 UTC - Add clarity to name of file being used in library example. (rust-lang/rust-by-example#1697) ## rust-lang/rustc-dev-guide 8 commits in fca8af6c154c6cde2512f1331cf2704f214a818e..6337ed17fb8dcd918d78b7d97d213e923530337c 2023-04-10 14:23:05 UTC to 2023-04-06 00:29:18 UTC - fix markup (rust-lang/rustc-dev-guide#1670) - Reorganize "Getting Started" and add a "What should I work on?" section (rust-lang/rustc-dev-guide#1665) - Clarify cfg(bootstrap) docs (rust-lang/rustc-dev-guide#1669) - Link to forge instead of duplicating toolstate info (rust-lang/rustc-dev-guide#1664) - Improve the landing page for contributing to the libstd docs (rust-lang/rustc-dev-guide#1666) - Various improvements to `check_line_lengths.sh` (rust-lang/rustc-dev-guide#1667) - Document how to ignore specific files in a diff (rust-lang/rustc-dev-guide#1668) - mention `git clone --depth 1` (rust-lang/rustc-dev-guide#1663)

Move "Getting Started" to the first page

6a1daff

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.

jyn514 force-pushed the getting-started branch from f9e08bc to bfcb494 Compare April 8, 2023 20:24

JohnTitor reviewed Apr 9, 2023

View reviewed changes

src/getting-started.md Outdated Show resolved Hide resolved

src/getting-started.md Outdated Show resolved Hide resolved

src/getting-started.md Outdated Show resolved Hide resolved

src/getting-started.md Outdated Show resolved Hide resolved

tshepang reviewed Apr 9, 2023

View reviewed changes

src/about-this-guide.md Outdated Show resolved Hide resolved

jyn514 force-pushed the getting-started branch from 847014f to fc3bd87 Compare April 9, 2023 19:35

tshepang reviewed Apr 9, 2023

View reviewed changes

jyn514 force-pushed the getting-started branch from fc3bd87 to 484e22d Compare April 9, 2023 20:15

jyn514 and others added 5 commits April 9, 2023 15:34

Fix link; remove duplicate link

daf9095

Make the "Asking Questions" section more useful

280cadc

- Update outdated chat platforms - Link to the community page - Suggest `git shortlog` for finding experts

Apply suggestions from code review

202dca0

Thank you JohnTitor for finding these! Co-authored-by: Yuki Okushi <jtitor@2k36.org>

Link to governance page

a0376d5

It has links to the specific channel/stream for each team.

jyn514 force-pushed the getting-started branch from 484e22d to a0376d5 Compare April 9, 2023 20:34

tshepang approved these changes Apr 9, 2023

View reviewed changes

tshepang merged commit 516194c into rust-lang:master Apr 9, 2023

jyn514 deleted the getting-started branch April 9, 2023 20:52

rustbot mentioned this pull request Apr 10, 2023

Update books rust-lang/rust#110149

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganize "Getting Started" and add a "What should I work on?" section #1665

Reorganize "Getting Started" and add a "What should I work on?" section #1665

jyn514 commented Apr 8, 2023

tshepang Apr 9, 2023 •

edited

Loading

jyn514 Apr 9, 2023

tshepang Apr 9, 2023

jyn514 Apr 9, 2023

tshepang Apr 9, 2023 •

edited

Loading

jyn514 Apr 9, 2023 •

edited

Loading

tshepang Apr 9, 2023

tshepang Apr 9, 2023 •

edited

Loading

jyn514 Apr 9, 2023

tshepang Apr 9, 2023

Reorganize "Getting Started" and add a "What should I work on?" section #1665

Reorganize "Getting Started" and add a "What should I work on?" section #1665

Conversation

jyn514 commented Apr 8, 2023

tshepang Apr 9, 2023 • edited Loading

Choose a reason for hiding this comment

jyn514 Apr 9, 2023

Choose a reason for hiding this comment

tshepang Apr 9, 2023

Choose a reason for hiding this comment

jyn514 Apr 9, 2023

Choose a reason for hiding this comment

tshepang Apr 9, 2023 • edited Loading

Choose a reason for hiding this comment

jyn514 Apr 9, 2023 • edited Loading

Choose a reason for hiding this comment

tshepang Apr 9, 2023

Choose a reason for hiding this comment

tshepang Apr 9, 2023 • edited Loading

Choose a reason for hiding this comment

jyn514 Apr 9, 2023

Choose a reason for hiding this comment

tshepang Apr 9, 2023

Choose a reason for hiding this comment

tshepang Apr 9, 2023 •

edited

Loading

tshepang Apr 9, 2023 •

edited

Loading

jyn514 Apr 9, 2023 •

edited

Loading

tshepang Apr 9, 2023 •

edited

Loading