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
|
||||
|
||||
- [Introduction](./contributing.md)
|
||||
- [Contribution Procedures](./contributing.md)
|
||||
- [About the compiler team](./compiler-team.md)
|
||||
- [Using Git](./git.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:
|
||||
|
||||
- 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
|
||||
- [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
|
||||
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/
|
||||
[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/
|
||||
[z]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
|
||||
|
|
|
|||
|
|
@ -1,31 +1,4 @@
|
|||
# Contributing to Rust
|
||||
|
||||
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.
|
||||
# Contribution Procedures
|
||||
|
||||
## 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
|
||||
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 (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
|
||||
database](https://github.com/rust-lang/team/tree/master/teams).
|
||||
|
||||
### Waiting for reviews
|
||||
|
||||
> NOTE
|
||||
>
|
||||
> 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,
|
||||
> 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
|
||||
|
||||
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
|
||||
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
|
||||
[@bors]: https://github.com/bors
|
||||
[merge-queue]: https://bors.rust-lang.org/queue/rust
|
||||
|
|
@ -198,7 +307,7 @@ the issue in question.
|
|||
|
||||
## 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
|
||||
|
||||
|
|
@ -400,64 +509,8 @@ This is used for [RFCs], issues, and pull requests.
|
|||
[rfcbot]: https://github.com/anp/rfcbot-rs/
|
||||
[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
|
||||
|
||||
For people new to Rust, and just starting to contribute, or even for
|
||||
more seasoned developers, some useful places to look for information
|
||||
are:
|
||||
This section has moved to the ["About this guide"][more-links] chapter.
|
||||
|
||||
* This guide contains information about how various parts of the
|
||||
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
|
||||
[more-links]: ./about-this-guide.md#other-places-to-find-information
|
||||
|
|
|
|||
|
|
@ -1,13 +1,31 @@
|
|||
# Getting Started
|
||||
|
||||
Thank you for your interest in contributing to Rust! There are many ways to
|
||||
contribute, and we appreciate all of them.
|
||||
|
||||
<!-- 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
|
||||
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).
|
||||
|
||||
[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
|
||||
|
||||
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
|
||||
"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
|
||||
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!
|
||||
- [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
|
||||
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
|
||||
[wd]: ./contributing.md#writing-documentation
|
||||
[wg]: https://rust-lang.github.io/compiler-team/working-groups/
|
||||
[triage]: ./contributing.md#issue-triage
|
||||
|
||||
## Contributor Procedures
|
||||
|
||||
There are some official procedures to know about. This is a tour of the
|
||||
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/
|
||||
This section has moved to the ["Contribution Procedures"](./contributing.md) chapter.
|
||||
|
||||
## Other Resources
|
||||
|
||||
- [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).
|
||||
This section has moved to the ["About this guide"][more-links] chapter.
|
||||
|
||||
[more-links]: ./about-this-guide.md#other-places-to-find-information
|
||||
|
|
|
|||
Loading…
Reference in New Issue