Rearrange the "getting started" and contributing.md sections
There was a lot of information duplicated between the two, and it wasn't clear which one to look. This commit changes `contributing.md` to be strictly for contribution procedures, and moves "what should I work on" sections to "Getting Started". This also consolidates the links in `about-this-guide.md` rather than spreading them between about-this-guide, getting-started, and contributing. I suggest using https://rustc-dev-guide.org/git.html#moving-large-sections-of-code to review this commit.
This commit is contained in:
Joshua Nelson
jyn
parent
cdd2e49a7a
commit
92102e0e8c
|
|
@ -35,7 +35,7 @@
|
||||||
|
|
||||||
# Contributing to Rust
|
# Contributing to Rust
|
||||||
|
|
||||||
- [Introduction](./contributing.md)
|
- [Contribution Procedures](./contributing.md)
|
||||||
- [About the compiler team](./compiler-team.md)
|
- [About the compiler team](./compiler-team.md)
|
||||||
- [Using Git](./git.md)
|
- [Using Git](./git.md)
|
||||||
- [Mastering @rustbot](./rustbot.md)
|
- [Mastering @rustbot](./rustbot.md)
|
||||||
|
|
|
||||||
|
|
@ -58,14 +58,52 @@ please see the corresponding [subsection on writing documentation in this guide]
|
||||||
|
|
||||||
You might also find the following sites useful:
|
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
|
||||||
- [Forge] -- contains documentation about Rust infrastructure, team procedures, and more
|
- [Forge] -- contains documentation about Rust infrastructure, team procedures, and more
|
||||||
- [compiler-team] -- the home-base for the Rust compiler team, with description
|
- [compiler-team] -- the home-base for the Rust compiler team, with description
|
||||||
of the team procedures, active working groups, and the team calendar.
|
of the team procedures, active working groups, and the team calendar.
|
||||||
- [std-dev-guide] -- a similar guide for developing the standard library.
|
- [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
|
||||||
|
discuss Rust's internals
|
||||||
|
- The [Rust reference][rr], even though it doesn't specifically talk about
|
||||||
|
Rust's internals, is a great resource nonetheless
|
||||||
|
- Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
|
||||||
|
- [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
|
||||||
|
- The [Rust Compiler Testing Docs][rctd]
|
||||||
|
- For [@bors], [this cheat sheet][cheatsheet] is helpful
|
||||||
|
- Google is always helpful when programming.
|
||||||
|
You can [search all Rust documentation][gsearchdocs] (the standard library,
|
||||||
|
the compiler, the books, the references, and the guides) to quickly find
|
||||||
|
information about the language and compiler.
|
||||||
|
- You can also use Rustdoc's built-in search feature to find documentation on
|
||||||
|
types and functions within the crates you're looking at. You can also search
|
||||||
|
by type signature! For example, searching for `* -> vec` should find all
|
||||||
|
functions that return a `Vec<T>`.
|
||||||
|
_Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
|
||||||
|
page!
|
||||||
|
|
||||||
|
|
||||||
|
[rustc dev guide]: about-this-guide.md
|
||||||
|
[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
|
||||||
|
[stddocs]: https://doc.rust-lang.org/std
|
||||||
|
[rif]: http://internals.rust-lang.org
|
||||||
|
[rr]: https://doc.rust-lang.org/book/README.html
|
||||||
|
[rustforge]: https://forge.rust-lang.org/
|
||||||
|
[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
|
||||||
|
[ro]: https://www.rustaceans.org/
|
||||||
|
[rctd]: tests/intro.md
|
||||||
|
[cheatsheet]: https://bors.rust-lang.org/
|
||||||
|
[Miri]: https://github.com/rust-lang/miri
|
||||||
|
[@bors]: https://github.com/bors
|
||||||
[GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/
|
[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/
|
[Forge]: https://forge.rust-lang.org/
|
||||||
[compiler-team]: https://github.com/rust-lang/compiler-team/
|
[compiler-team]: https://github.com/rust-lang/compiler-team/
|
||||||
[std-dev-guide]: https://std-dev-guide.rust-lang.org/
|
[std-dev-guide]: https://std-dev-guide.rust-lang.org/
|
||||||
|
[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
|
||||||
|
|
|
||||||
|
|
@ -1,31 +1,4 @@
|
||||||
# Contributing to Rust
|
# Contribution Procedures
|
||||||
|
|
||||||
Thank you for your interest in contributing to Rust! There are many ways to
|
|
||||||
contribute, and we appreciate all of them.
|
|
||||||
|
|
||||||
<!-- toc -->
|
|
||||||
|
|
||||||
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].
|
|
||||||
|
|
||||||
As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
|
|
||||||
|
|
||||||
If this is your first time contributing, the [Getting Started] and
|
|
||||||
[walkthrough] chapters can give you a good example of how a typical
|
|
||||||
contribution would go.
|
|
||||||
|
|
||||||
[internals]: https://internals.rust-lang.org
|
|
||||||
[rust-discord]: http://discord.gg/rust-lang
|
|
||||||
[rust-zulip]: https://rust-lang.zulipchat.com
|
|
||||||
[coc]: https://www.rust-lang.org/conduct.html
|
|
||||||
[walkthrough]: ./walkthrough.md
|
|
||||||
[Getting Started]: ./getting-started.md
|
|
||||||
|
|
||||||
## Feature Requests
|
|
||||||
|
|
||||||
Feature requests need to go through a process to be approved by the relevant
|
|
||||||
teams. Usually this requires a Final Comment Period (FCP) or even a Request for
|
|
||||||
Comments (RFC). See [Getting Started] for more information about these processes.
|
|
||||||
|
|
||||||
## Bug Reports
|
## Bug Reports
|
||||||
|
|
||||||
|
|
@ -58,6 +31,121 @@ Opening an issue is as easy as following [this
|
||||||
link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
|
link](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
|
||||||
in the appropriate provided template.
|
in the appropriate provided template.
|
||||||
|
|
||||||
|
## Bug Fixes or "Normal" code changes
|
||||||
|
|
||||||
|
For most PRs, no special procedures are needed. You can just [open a PR][prs], and it
|
||||||
|
will be reviewed, approved, and merged. This includes most bug fixes,
|
||||||
|
refactorings, and other user-invisible changes. The next few sections talk
|
||||||
|
about exceptions to this rule.
|
||||||
|
|
||||||
|
Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft
|
||||||
|
PRs][draft]. Some people prefer to do this so they can get feedback along the
|
||||||
|
way or share their code with a collaborator. Others do this so they can utilize
|
||||||
|
the CI to build and test their PR (e.g. if you are developing on a laptop).
|
||||||
|
|
||||||
|
[prs]: #pull-requests
|
||||||
|
[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
|
||||||
|
|
||||||
|
## New Features
|
||||||
|
|
||||||
|
Rust has strong backwards-compatibility guarantees. Thus, new features can't
|
||||||
|
just be implemented directly in stable Rust. Instead, we have 3 release
|
||||||
|
channels: stable, beta, and nightly.
|
||||||
|
|
||||||
|
- **Stable**: this is the latest stable release for general usage.
|
||||||
|
- **Beta**: this is the next release (will be stable within 6 weeks).
|
||||||
|
- **Nightly**: follows the `master` branch of the repo. This is the only
|
||||||
|
channel where unstable, incomplete, or experimental features are usable with
|
||||||
|
feature gates.
|
||||||
|
|
||||||
|
In order to implement a new feature, usually you will need to go through [the
|
||||||
|
RFC process][rfc] to propose a design, have discussions, etc. In some cases,
|
||||||
|
small features can be added with only an FCP ([see below][break]). If in doubt, ask the
|
||||||
|
compiler, language, or libs team (whichever is most relevant).
|
||||||
|
|
||||||
|
[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md
|
||||||
|
|
||||||
|
After a feature is approved to be added, a tracking issue is created on the
|
||||||
|
`rust-lang/rust` repo, which tracks the progress towards the implementation of
|
||||||
|
the feature, any bugs reported, and eventually stabilization.
|
||||||
|
|
||||||
|
The feature then needs to be implemented behind a feature gate, which prevents
|
||||||
|
it from being accidentally used.
|
||||||
|
|
||||||
|
Finally, somebody may propose stabilizing the feature in an upcoming version of
|
||||||
|
Rust. This requires a Final Comment Period ([see below][break]) to get the
|
||||||
|
approval of the relevant teams.
|
||||||
|
|
||||||
|
After that, the feature gate can be removed and the feature turned on for all users.
|
||||||
|
|
||||||
|
For more details on this process, see [this chapter on implementing new
|
||||||
|
features.](./implementing_new_features.md)
|
||||||
|
|
||||||
|
### Breaking Changes
|
||||||
|
|
||||||
|
As mentioned above, Rust has strong backwards-compatibility guarantees. To this
|
||||||
|
end, we are reluctant to make breaking changes. However, sometimes they are
|
||||||
|
needed to correct compiler bugs (e.g. code that compiled but should not) or
|
||||||
|
make progress on some features.
|
||||||
|
|
||||||
|
Depending on the scale of the breakage, there are a few different actions that
|
||||||
|
can be taken. If the reviewer believes the breakage is very minimal (i.e. very
|
||||||
|
unlikely to be actually encountered by users), they may just merge the change.
|
||||||
|
More often, they will request a Final Comment Period (FCP), which calls for
|
||||||
|
rough consensus among the members of a relevant team. The team members can
|
||||||
|
discuss the issue and either accept, reject, or request changes on the PR.
|
||||||
|
|
||||||
|
If the scale of breakage is large, a deprecation warning may be needed. This is
|
||||||
|
a warning that the compiler will display to users whose code will break in the
|
||||||
|
future. After some time, an FCP can be used to move forward with the actual
|
||||||
|
breakage.
|
||||||
|
|
||||||
|
If the scale of breakage is unknown, a team member or contributor may request a
|
||||||
|
[crater] run. This is a bot that will compile all crates.io crates and many
|
||||||
|
public github repos with the compiler with your changes. A report will then be
|
||||||
|
generated with crates that ceased to compile with or began to compile with your
|
||||||
|
changes. Crater runs can take a few days to complete.
|
||||||
|
|
||||||
|
[crater]: https://github.com/rust-lang/crater
|
||||||
|
|
||||||
|
### Major Changes
|
||||||
|
|
||||||
|
The compiler team has a special process for large changes, whether or not they
|
||||||
|
cause breakage. This process is called a Major Change Proposal (MCP). MCP is a
|
||||||
|
relatively lightweight mechanism for getting feedback on large changes to the
|
||||||
|
compiler (as opposed to a full RFC or a design meeting with the team).
|
||||||
|
|
||||||
|
Example of things that might require MCPs include major refactorings, changes
|
||||||
|
to important types, or important changes to how the compiler does something, or
|
||||||
|
smaller user-facing changes.
|
||||||
|
|
||||||
|
**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work
|
||||||
|
into a PR that ends up not getting merged!** [See this document][mcpinfo] for
|
||||||
|
more info on MCPs.
|
||||||
|
|
||||||
|
[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html
|
||||||
|
[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
|
||||||
|
Compiler performance is important. We have put a lot of effort over the last
|
||||||
|
few years into [gradually improving it][perfdash].
|
||||||
|
|
||||||
|
[perfdash]: https://perf.rust-lang.org/dashboard.html
|
||||||
|
|
||||||
|
If you suspect that your change may cause a performance regression (or
|
||||||
|
improvement), you can request a "perf run" (your reviewer may also request one
|
||||||
|
before approving). This is yet another bot that will compile a collection of
|
||||||
|
benchmarks on a compiler with your changes. The numbers are reported
|
||||||
|
[here][perf], and you can see a comparison of your changes against the latest
|
||||||
|
master.
|
||||||
|
|
||||||
|
For an introduction to the performance of Rust code in general
|
||||||
|
which would also be useful in rustc development, see [The Rust Performance Book].
|
||||||
|
|
||||||
|
[perf]: https://perf.rust-lang.org
|
||||||
|
[The Rust Performance Book]: https://nnethercote.github.io/perf-book/
|
||||||
|
|
||||||
## Pull Requests
|
## Pull Requests
|
||||||
|
|
||||||
Pull requests (or PRs for short) are the primary mechanism we use to change Rust.
|
Pull requests (or PRs for short) are the primary mechanism we use to change Rust.
|
||||||
|
|
@ -96,6 +184,8 @@ For a full list of possible `groupname` check the `adhoc_groups` section at the
|
||||||
or the list of teams in the [rust-lang teams
|
or the list of teams in the [rust-lang teams
|
||||||
database](https://github.com/rust-lang/team/tree/master/teams).
|
database](https://github.com/rust-lang/team/tree/master/teams).
|
||||||
|
|
||||||
|
### Waiting for reviews
|
||||||
|
|
||||||
> NOTE
|
> NOTE
|
||||||
>
|
>
|
||||||
> Pull request reviewers are often working at capacity,
|
> Pull request reviewers are often working at capacity,
|
||||||
|
|
@ -113,6 +203,23 @@ database](https://github.com/rust-lang/team/tree/master/teams).
|
||||||
> the author is ready for a review,
|
> the author is ready for a review,
|
||||||
> and this PR will be queued again in the reviewer's queue.
|
> and this PR will be queued again in the reviewer's queue.
|
||||||
|
|
||||||
|
Please note that the reviewers are humans, who for the most part work on `rustc`
|
||||||
|
in their free time. This means that they can take some time to respond and review
|
||||||
|
your PR. It also means that reviewers can miss some PRs that are assigned to them.
|
||||||
|
|
||||||
|
To try to move PRs forward, the Triage WG regularly goes through all PRs that
|
||||||
|
are waiting for review and haven't been discussed for at least 2 weeks. If you
|
||||||
|
don't get a review within 2 weeks, feel free to ask the Triage WG on
|
||||||
|
Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be
|
||||||
|
on vacation, etc.
|
||||||
|
|
||||||
|
The reviewer may request some changes using the GitHub code review interface.
|
||||||
|
They may also request special procedures (such as a [crater] run; [see
|
||||||
|
below][break]) for some PRs.
|
||||||
|
|
||||||
|
[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371
|
||||||
|
[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage
|
||||||
|
[break]: #breaking-changes
|
||||||
### CI
|
### CI
|
||||||
|
|
||||||
In addition to being reviewed by a human, pull requests are automatically tested
|
In addition to being reviewed by a human, pull requests are automatically tested
|
||||||
|
|
@ -152,6 +259,8 @@ Changes that are rolled up are tested and merged alongside other PRs, to
|
||||||
speed the process up. Typically only small changes that are expected not to conflict
|
speed the process up. Typically only small changes that are expected not to conflict
|
||||||
with one another are marked as "always roll up".
|
with one another are marked as "always roll up".
|
||||||
|
|
||||||
|
Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand.
|
||||||
|
|
||||||
[@rustbot]: https://github.com/rustbot
|
[@rustbot]: https://github.com/rustbot
|
||||||
[@bors]: https://github.com/bors
|
[@bors]: https://github.com/bors
|
||||||
[merge-queue]: https://bors.rust-lang.org/queue/rust
|
[merge-queue]: https://bors.rust-lang.org/queue/rust
|
||||||
|
|
@ -198,7 +307,7 @@ the issue in question.
|
||||||
|
|
||||||
## External Dependencies
|
## External Dependencies
|
||||||
|
|
||||||
This sections has moved to ["Using External Repositories"](./external-repos.md).
|
This section has moved to ["Using External Repositories"](./external-repos.md).
|
||||||
|
|
||||||
## Writing Documentation
|
## Writing Documentation
|
||||||
|
|
||||||
|
|
@ -400,64 +509,8 @@ This is used for [RFCs], issues, and pull requests.
|
||||||
[rfcbot]: https://github.com/anp/rfcbot-rs/
|
[rfcbot]: https://github.com/anp/rfcbot-rs/
|
||||||
[RFCs]: https://github.com/rust-lang/rfcs
|
[RFCs]: https://github.com/rust-lang/rfcs
|
||||||
|
|
||||||
## Out-of-tree Contributions
|
|
||||||
|
|
||||||
There are a number of other ways to contribute to Rust that don't deal with
|
|
||||||
rust-lang/rust:
|
|
||||||
|
|
||||||
* Answer questions in the _Get Help!_ channels on the [Rust Discord
|
|
||||||
server][rust-discord], on [users.rust-lang.org][users], or on
|
|
||||||
[StackOverflow][so].
|
|
||||||
* Participate in the [RFC process](https://github.com/rust-lang/rfcs).
|
|
||||||
* Find a [requested community library][community-library], build it, and publish
|
|
||||||
it to [Crates.io](http://crates.io). Easier said than done, but very, very
|
|
||||||
valuable!
|
|
||||||
|
|
||||||
[rust-discord]: https://discord.gg/rust-lang
|
|
||||||
[users]: https://users.rust-lang.org/
|
|
||||||
[so]: http://stackoverflow.com/questions/tagged/rust
|
|
||||||
[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
|
|
||||||
|
|
||||||
## Helpful Links and Information
|
## Helpful Links and Information
|
||||||
|
|
||||||
For people new to Rust, and just starting to contribute, or even for
|
This section has moved to the ["About this guide"][more-links] chapter.
|
||||||
more seasoned developers, some useful places to look for information
|
|
||||||
are:
|
|
||||||
|
|
||||||
* This guide contains information about how various parts of the
|
[more-links]: ./about-this-guide.md#other-places-to-find-information
|
||||||
compiler work and how to contribute to the compiler
|
|
||||||
* [Rust Forge][rustforge] contains additional documentation, including
|
|
||||||
write-ups of how to achieve common tasks
|
|
||||||
* The [Rust Internals forum][rif], a place to ask questions and
|
|
||||||
discuss Rust's internals
|
|
||||||
* The [generated documentation for Rust's compiler][gdfrustc]
|
|
||||||
* The [Rust reference][rr], even though it doesn't specifically talk about
|
|
||||||
Rust's internals, is a great resource nonetheless
|
|
||||||
* Although out of date, [Tom Lee's great blog article][tlgba] is very helpful
|
|
||||||
* [rustaceans.org][ro] is helpful, but mostly dedicated to IRC
|
|
||||||
* The [Rust Compiler Testing Docs][rctd]
|
|
||||||
* For [@bors], [this cheat sheet][cheatsheet] is helpful
|
|
||||||
* Google is always helpful when programming.
|
|
||||||
You can [search all Rust documentation][gsearchdocs] (the standard library,
|
|
||||||
the compiler, the books, the references, and the guides) to quickly find
|
|
||||||
information about the language and compiler.
|
|
||||||
* You can also use Rustdoc's built-in search feature to find documentation on
|
|
||||||
types and functions within the crates you're looking at. You can also search
|
|
||||||
by type signature! For example, searching for `* -> vec` should find all
|
|
||||||
functions that return a `Vec<T>`.
|
|
||||||
_Hint:_ Find more tips and keyboard shortcuts by typing `?` on any Rustdoc
|
|
||||||
page!
|
|
||||||
* Don't be afraid to ask! The Rust community is friendly and helpful.
|
|
||||||
|
|
||||||
[rustc dev guide]: about-this-guide.md
|
|
||||||
[gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
|
|
||||||
[gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
|
|
||||||
[stddocs]: https://doc.rust-lang.org/std
|
|
||||||
[rif]: http://internals.rust-lang.org
|
|
||||||
[rr]: https://doc.rust-lang.org/book/README.html
|
|
||||||
[rustforge]: https://forge.rust-lang.org/
|
|
||||||
[tlgba]: https://tomlee.co/2014/04/a-more-detailed-tour-of-the-rust-compiler/
|
|
||||||
[ro]: https://www.rustaceans.org/
|
|
||||||
[rctd]: tests/intro.md
|
|
||||||
[cheatsheet]: https://bors.rust-lang.org/
|
|
||||||
[Miri]: https://github.com/rust-lang/miri
|
|
||||||
|
|
|
||||||
|
|
@ -1,13 +1,31 @@
|
||||||
# Getting Started
|
# Getting Started
|
||||||
|
|
||||||
|
Thank you for your interest in contributing to Rust! There are many ways to
|
||||||
|
contribute, and we appreciate all of them.
|
||||||
|
|
||||||
<!-- toc -->
|
<!-- toc -->
|
||||||
|
|
||||||
|
If this is your first time contributing, the [walkthrough] chapter can give you a good example of
|
||||||
|
how a typical contribution would go.
|
||||||
|
|
||||||
This documentation is _not_ intended to be comprehensive; it is meant to be a
|
This documentation is _not_ intended to be comprehensive; it is meant to be a
|
||||||
quick guide for the most useful things. For more information, [see this
|
quick guide for the most useful things. For more information, [see this
|
||||||
chapter on how to build and run the compiler](./building/how-to-build-and-run.md).
|
chapter on how to build and run the compiler](./building/how-to-build-and-run.md).
|
||||||
|
|
||||||
|
[internals]: https://internals.rust-lang.org
|
||||||
|
[rust-discord]: http://discord.gg/rust-lang
|
||||||
|
[rust-zulip]: https://rust-lang.zulipchat.com
|
||||||
|
[coc]: https://www.rust-lang.org/conduct.html
|
||||||
|
[walkthrough]: ./walkthrough.md
|
||||||
|
[Getting Started]: ./getting-started.md
|
||||||
|
|
||||||
## Asking Questions
|
## 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].
|
||||||
|
|
||||||
|
As a reminder, all contributors are expected to follow our [Code of Conduct][coc].
|
||||||
|
|
||||||
The compiler team (or `t-compiler`) usually hangs out in Zulip [in this
|
The compiler team (or `t-compiler`) usually hangs out in Zulip [in this
|
||||||
"stream"][z]; it will be easiest to get questions answered there.
|
"stream"][z]; it will be easiest to get questions answered there.
|
||||||
|
|
||||||
|
|
@ -69,172 +87,33 @@ incredibly helpful:
|
||||||
- [Writing documentation][wd]: if you are feeling a bit more intrepid, you could try
|
- [Writing documentation][wd]: if you are feeling a bit more intrepid, you could try
|
||||||
to read a part of the code and write doc comments for it. This will help you
|
to read a part of the code and write doc comments for it. This will help you
|
||||||
to learn some part of the compiler while also producing a useful artifact!
|
to learn some part of the compiler while also producing a useful artifact!
|
||||||
|
- [Triaging issues][triage]: categorizing, replicating, and minimizing issues is very helpful to the Rust maintainers.
|
||||||
- [Working groups][wg]: there are a bunch of working groups on a wide variety
|
- [Working groups][wg]: there are a bunch of working groups on a wide variety
|
||||||
of rust-related things.
|
of rust-related things.
|
||||||
|
- Answer questions in the _Get Help!_ channels on the [Rust Discord
|
||||||
|
server][rust-discord], on [users.rust-lang.org][users], or on
|
||||||
|
[StackOverflow][so].
|
||||||
|
- Participate in the [RFC process](https://github.com/rust-lang/rfcs).
|
||||||
|
- Find a [requested community library][community-library], build it, and publish
|
||||||
|
it to [Crates.io](http://crates.io). Easier said than done, but very, very
|
||||||
|
valuable!
|
||||||
|
|
||||||
|
[rust-discord]: https://discord.gg/rust-lang
|
||||||
|
[users]: https://users.rust-lang.org/
|
||||||
|
[so]: http://stackoverflow.com/questions/tagged/rust
|
||||||
|
[community-library]: https://github.com/rust-lang/rfcs/labels/A-community-library
|
||||||
|
|
||||||
[iceb]: ./notification-groups/cleanup-crew.md
|
[iceb]: ./notification-groups/cleanup-crew.md
|
||||||
[wd]: ./contributing.md#writing-documentation
|
[wd]: ./contributing.md#writing-documentation
|
||||||
[wg]: https://rust-lang.github.io/compiler-team/working-groups/
|
[wg]: https://rust-lang.github.io/compiler-team/working-groups/
|
||||||
|
[triage]: ./contributing.md#issue-triage
|
||||||
|
|
||||||
## Contributor Procedures
|
## Contributor Procedures
|
||||||
|
|
||||||
There are some official procedures to know about. This is a tour of the
|
This section has moved to the ["Contribution Procedures"](./contributing.md) chapter.
|
||||||
highlights, but there are a lot more details, which we will link to below.
|
|
||||||
|
|
||||||
### Code Review
|
|
||||||
|
|
||||||
When you open a PR on the `rust-lang/rust` repo, a bot called `@rustbot` will
|
|
||||||
automatically assign a reviewer to the PR based on which files you changed.
|
|
||||||
The reviewer is the person that will approve the PR to be tested and merged.
|
|
||||||
If you want a specific reviewer (e.g. a team member you've been working with),
|
|
||||||
you can specifically request them by writing `r? @user` (e.g. `r? @jyn514`) in
|
|
||||||
either the original post or a followup comment
|
|
||||||
(you can see [this comment][r?] for example).
|
|
||||||
|
|
||||||
Please note that the reviewers are humans, who for the most part work on `rustc`
|
|
||||||
in their free time. This means that they can take some time to respond and review
|
|
||||||
your PR. It also means that reviewers can miss some PRs that are assigned to them.
|
|
||||||
|
|
||||||
To try to move PRs forward, the Triage WG regularly goes through all PRs that
|
|
||||||
are waiting for review and haven't been discussed for at least 2 weeks. If you
|
|
||||||
don't get a review within 2 weeks, feel free to ask the Triage WG on
|
|
||||||
Zulip ([#t-release/triage]). They have knowledge of when to ping, who might be
|
|
||||||
on vacation, etc.
|
|
||||||
|
|
||||||
The reviewer may request some changes using the GitHub code review interface.
|
|
||||||
They may also request special procedures (such as a [crater] run; [see
|
|
||||||
below][break]) for some PRs.
|
|
||||||
|
|
||||||
[r?]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712692371
|
|
||||||
[#t-release/triage]: https://rust-lang.zulipchat.com/#narrow/stream/242269-t-release.2Ftriage
|
|
||||||
[break]: #breaking-changes
|
|
||||||
|
|
||||||
When the PR is ready to be merged, the reviewer will issue a command to
|
|
||||||
`@bors`, the CI bot. Usually, this is `@bors r+` or `@bors r=user` to approve
|
|
||||||
a PR (there are few other commands, but they are less relevant here).
|
|
||||||
You can see [this comment][r+] for example. This puts the PR in [bors's queue][bors]
|
|
||||||
to be tested and merged. Be patient; this can take a while and the queue can
|
|
||||||
sometimes be long. PRs are never merged by hand.
|
|
||||||
|
|
||||||
[r+]: https://github.com/rust-lang/rust/pull/78133#issuecomment-712726339
|
|
||||||
[bors]: https://bors.rust-lang.org/queue/rust
|
|
||||||
|
|
||||||
### Bug Fixes or "Normal" code changes
|
|
||||||
|
|
||||||
For most PRs, no special procedures are needed. You can just open a PR, and it
|
|
||||||
will be reviewed, approved, and merged. This includes most bug fixes,
|
|
||||||
refactorings, and other user-invisible changes. The next few sections talk
|
|
||||||
about exceptions to this rule.
|
|
||||||
|
|
||||||
Also, note that it is perfectly acceptable to open WIP PRs or GitHub [Draft
|
|
||||||
PRs][draft]. Some people prefer to do this so they can get feedback along the
|
|
||||||
way or share their code with a collaborator. Others do this so they can utilize
|
|
||||||
the CI to build and test their PR (e.g. if you are developing on a laptop).
|
|
||||||
|
|
||||||
[draft]: https://github.blog/2019-02-14-introducing-draft-pull-requests/
|
|
||||||
|
|
||||||
### New Features
|
|
||||||
|
|
||||||
Rust has strong backwards-compatibility guarantees. Thus, new features can't
|
|
||||||
just be implemented directly in stable Rust. Instead, we have 3 release
|
|
||||||
channels: stable, beta, and nightly.
|
|
||||||
|
|
||||||
- **Stable**: this is the latest stable release for general usage.
|
|
||||||
- **Beta**: this is the next release (will be stable within 6 weeks).
|
|
||||||
- **Nightly**: follows the `master` branch of the repo. This is the only
|
|
||||||
channel where unstable, incomplete, or experimental features are usable with
|
|
||||||
feature gates.
|
|
||||||
|
|
||||||
In order to implement a new feature, usually you will need to go through [the
|
|
||||||
RFC process][rfc] to propose a design, have discussions, etc. In some cases,
|
|
||||||
small features can be added with only an FCP ([see below][break]). If in doubt, ask the
|
|
||||||
compiler, language, or libs team (whichever is most relevant).
|
|
||||||
|
|
||||||
[rfc]: https://github.com/rust-lang/rfcs/blob/master/README.md
|
|
||||||
|
|
||||||
After a feature is approved to be added, a tracking issue is created on the
|
|
||||||
`rust-lang/rust` repo, which tracks the progress towards the implementation of
|
|
||||||
the feature, any bugs reported, and eventually stabilization.
|
|
||||||
|
|
||||||
The feature then needs to be implemented behind a feature gate, which prevents
|
|
||||||
it from being accidentally used.
|
|
||||||
|
|
||||||
Finally, somebody may propose stabilizing the feature in an upcoming version of
|
|
||||||
Rust. This requires a Final Comment Period ([see below][break]) to get the
|
|
||||||
approval of the relevant teams.
|
|
||||||
|
|
||||||
After that, the feature gate can be removed and the feature turned on for all users.
|
|
||||||
|
|
||||||
For more details on this process, see [this chapter on implementing new
|
|
||||||
features.](./implementing_new_features.md)
|
|
||||||
|
|
||||||
### Breaking Changes
|
|
||||||
|
|
||||||
As mentioned above, Rust has strong backwards-compatibility guarantees. To this
|
|
||||||
end, we are reluctant to make breaking changes. However, sometimes they are
|
|
||||||
needed to correct compiler bugs (e.g. code that compiled but should not) or
|
|
||||||
make progress on some features.
|
|
||||||
|
|
||||||
Depending on the scale of the breakage, there are a few different actions that
|
|
||||||
can be taken. If the reviewer believes the breakage is very minimal (i.e. very
|
|
||||||
unlikely to be actually encountered by users), they may just merge the change.
|
|
||||||
More often, they will request a Final Comment Period (FCP), which calls for
|
|
||||||
rough consensus among the members of a relevant team. The team members can
|
|
||||||
discuss the issue and either accept, reject, or request changes on the PR.
|
|
||||||
|
|
||||||
If the scale of breakage is large, a deprecation warning may be needed. This is
|
|
||||||
a warning that the compiler will display to users whose code will break in the
|
|
||||||
future. After some time, an FCP can be used to move forward with the actual
|
|
||||||
breakage.
|
|
||||||
|
|
||||||
If the scale of breakage is unknown, a team member or contributor may request a
|
|
||||||
[crater] run. This is a bot that will compile all crates.io crates and many
|
|
||||||
public github repos with the compiler with your changes. A report will then be
|
|
||||||
generated with crates that ceased to compile with or began to compile with your
|
|
||||||
changes. Crater runs can take a few days to complete.
|
|
||||||
|
|
||||||
[crater]: https://github.com/rust-lang/crater
|
|
||||||
|
|
||||||
### Major Changes
|
|
||||||
|
|
||||||
The compiler team has a special process for large changes, whether or not they
|
|
||||||
cause breakage. This process is called a Major Change Proposal (MCP). MCP is a
|
|
||||||
relatively lightweight mechanism for getting feedback on large changes to the
|
|
||||||
compiler (as opposed to a full RFC or a design meeting with the team).
|
|
||||||
|
|
||||||
Example of things that might require MCPs include major refactorings, changes
|
|
||||||
to important types, or important changes to how the compiler does something, or
|
|
||||||
smaller user-facing changes.
|
|
||||||
|
|
||||||
**When in doubt, ask on [zulip][z]. It would be a shame to put a lot of work
|
|
||||||
into a PR that ends up not getting merged!** [See this document][mcpinfo] for
|
|
||||||
more info on MCPs.
|
|
||||||
|
|
||||||
[mcpinfo]: https://forge.rust-lang.org/compiler/mcp.html
|
|
||||||
|
|
||||||
### Performance
|
|
||||||
|
|
||||||
Compiler performance is important. We have put a lot of effort over the last
|
|
||||||
few years into [gradually improving it][perfdash].
|
|
||||||
|
|
||||||
[perfdash]: https://perf.rust-lang.org/dashboard.html
|
|
||||||
|
|
||||||
If you suspect that your change may cause a performance regression (or
|
|
||||||
improvement), you can request a "perf run" (your reviewer may also request one
|
|
||||||
before approving). This is yet another bot that will compile a collection of
|
|
||||||
benchmarks on a compiler with your changes. The numbers are reported
|
|
||||||
[here][perf], and you can see a comparison of your changes against the latest
|
|
||||||
master.
|
|
||||||
|
|
||||||
For an introduction to the performance of Rust code in general
|
|
||||||
which would also be useful in rustc development, see [The Rust Performance Book].
|
|
||||||
|
|
||||||
[perf]: https://perf.rust-lang.org
|
|
||||||
[The Rust Performance Book]: https://nnethercote.github.io/perf-book/
|
|
||||||
|
|
||||||
## Other Resources
|
## Other Resources
|
||||||
|
|
||||||
- [The t-compiler zulip][z]
|
This section has moved to the ["About this guide"][more-links] chapter.
|
||||||
- [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.
|
[more-links]: ./about-this-guide.md#other-places-to-find-information
|
||||||
- `#contribute` and `#wg-rustup` on [Discord](https://discord.gg/rust-lang).
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue