Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 6 commits into from
Apr 9, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
# Summary

[About this guide](./about-this-guide.md)

[Getting Started](./getting-started.md)
[About this guide](./about-this-guide.md)

---

Expand Down
5 changes: 2 additions & 3 deletions src/about-this-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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/
Expand Down
5 changes: 2 additions & 3 deletions src/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -373,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

Expand Down
77 changes: 70 additions & 7 deletions src/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,14 @@ 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 [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].

Expand All @@ -48,6 +54,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
Expand All @@ -60,20 +72,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 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)
- [Move UI tests to subdirectories](https://github.com/rust-lang/rust/issues/73494)

## Contributing code to other Rust projects
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
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.
Expand Down Expand Up @@ -108,6 +167,10 @@ 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.
Expand Down