From bdf0a199107fbb27bb163174b38e42a6ff549029 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 25 Mar 2023 17:37:02 -0500 Subject: [PATCH 1/6] Move some info from "Getting Started" to "How to build and run" "Getting Started" is already *very* long; this shrinks it a bit, and puts similar info closer together. --- src/building/how-to-build-and-run.md | 31 +++++++++- src/getting-started.md | 86 ++-------------------------- 2 files changed, 33 insertions(+), 84 deletions(-) diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 300bc349e..564136453 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -52,7 +52,34 @@ If you have already built `rustc` and you change settings related to LLVM, then execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x.py clean` will not cause a rebuild of LLVM. -## Building the compiler +## Common `x.py` commands + +Here are the basic invocations of the `x.py` commands most commonly used when +working on `rustc`, `std`, `rustdoc`, and other tools. + +| Command | When to use it | +| --- | --- | +| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] | +| `./x.py build` | Builds `rustc`, `std`, and `rustdoc` | +| `./x.py test` | Runs all tests | +| `./x.py fmt` | Formats all code | + +As written, these commands are reasonable starting points. However, there are +additional options and arguments for each of them that are worth learning for +serious development work. In particular, `./x.py build` and `./x.py test` +provide many ways to compile or test a subset of the code, which can save a lot +of time. + +Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`, +and `src/tools` directories. So, you can simply run `x.py test tidy` instead of +`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`. + +[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc + +See the chapters on [building](./building/how-to-build-and-run.md), +[testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details. + +### Building the compiler Note that building will require a relatively large amount of storage space. You may want to have upwards of 10 or 15 gigabytes available to build the compiler. @@ -98,7 +125,7 @@ build. The **full** `rustc` build (what you get with `./x.py build You almost never need to do this. -## Build specific components +### Build specific components If you are working on the standard library, you probably don't need to build the compiler unless you are planning to use a recently added nightly feature. diff --git a/src/getting-started.md b/src/getting-started.md index bc294d1b3..8c00dc6a9 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -44,86 +44,9 @@ just create noise, so we ask that you be mindful of the fact that the ## Cloning and Building -### System Requirements +See ["How to build and run the compiler"](./building//how-to-build-and-run.md). -Internet access is required. - -The most notable software requirement is that you will need Python 2 or 3, but -there are various others. - -The following hardware is recommended. -* 30GB+ of free disk space. -* 8GB+ RAM -* 2+ cores - -More powerful machines will lead to much faster builds. There are various -strategies to work around lesser hardware in the following chapters. - -See [this chapter][prereqs] for more details about software and hardware prerequisites. - -[prereqs]: ./building/prerequisites.md - -### Cloning - -You can just do a normal git clone: - -```sh -git clone https://github.com/rust-lang/rust.git -cd rust -``` - -### `x.py` Intro - -`rustc` is a [bootstrapping] compiler, which makes it more complex than a -typical Rust program. As a result, you cannot use Cargo to build it. Instead -you must use the special tool `x.py`. It is used for the things Cargo is -normally used for: building, testing, creating releases, formatting, etc. - -[bootstrapping]: ./building/bootstrapping.md - -### Configuring the compiler - -In the top level of the repo: - -```sh -$ ./x.py setup -``` - -This will do some initialization and walk you through an interactive setup to -create `config.toml`, the primary configuration file. - -See [this chapter][config] for more info about configuration. - -[config]: ./building/how-to-build-and-run.md#create-a-configtoml - -### Common `x.py` commands - -Here are the basic invocations of the `x.py` commands most commonly used when -working on `rustc`, `std`, `rustdoc`, and other tools. - -| Command | When to use it | -| --- | --- | -| `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] | -| `./x.py build` | Builds `rustc`, `std`, and `rustdoc` | -| `./x.py test` | Runs all tests | -| `./x.py fmt` | Formats all code | - -As written, these commands are reasonable starting points. However, there are -additional options and arguments for each of them that are worth learning for -serious development work. In particular, `./x.py build` and `./x.py test` -provide many ways to compile or test a subset of the code, which can save a lot -of time. - -Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`, -and `src/tools` directories. So, you can simply run `x.py test tidy` instead of -`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`. - -[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc - -See the chapters on [building](./building/how-to-build-and-run.md), -[testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details. - -### Contributing code to other Rust projects +## 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. @@ -132,7 +55,7 @@ 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. @@ -311,8 +234,7 @@ which would also be useful in rustc development, see [The Rust Performance Book] ## Other Resources -- This guide: talks about how `rustc` works - [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 `#rustdoc` on [Discord](https://discord.gg/rust-lang). +- `#contribute` and `#wg-rustup` on [Discord](https://discord.gg/rust-lang). From f9ad33a6da878ae5297a46bc5b837e51df1feb76 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 25 Mar 2023 17:49:55 -0500 Subject: [PATCH 2/6] Outline the external repositories section This is advanced info that most contributors won't need to know; and for experienced contributors, it means the info is at the top of the page instead of needing to scroll. --- src/SUMMARY.md | 1 + src/contributing.md | 146 +-------------------------------------- src/external-repos.md | 157 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 160 insertions(+), 144 deletions(-) create mode 100644 src/external-repos.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3cd6989a5..ccca3acf5 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -46,6 +46,7 @@ - [Stabilizing Features](./stabilization_guide.md) - [Feature Gates](./feature-gates.md) - [Coding conventions](./conventions.md) +- [Using external repositories](./external-repos.md) - [Fuzzing](./fuzzing.md) - [Notification groups](notification-groups/about.md) - [ARM](notification-groups/arm.md) diff --git a/src/contributing.md b/src/contributing.md index aa05ba98c..8a918a970 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -196,151 +196,9 @@ the issue in question. [labeling]: ./rustbot.md#issue-relabeling [closing-keywords]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue -### External Dependencies (subtree) - -As a developer to this repository, you don't have to treat the following external projects -differently from other crates that are directly in this repo: - -* [Clippy](https://github.com/rust-lang/rust-clippy) -* [Miri] -* [rustfmt](https://github.com/rust-lang/rustfmt) -* [rust-analyzer](https://github.com/rust-lang/rust-analyzer) - -In contrast to `submodule` dependencies -(see below for those), the `subtree` dependencies are just regular files and directories which can -be updated in tree. However, if possible, enhancements, bug fixes, etc. specific -to these tools should be filed against the tools directly in their respective -upstream repositories. The exception is that when rustc changes are required to -implement a new tool feature or test, that should happen in one collective rustc PR. - -#### Synchronizing a subtree - -Periodically the changes made to subtree based dependencies need to be synchronized between this -repository and the upstream tool repositories. - -Subtree synchronizations are typically handled by the respective tool maintainers. Other users -are welcome to submit synchronization PRs, however, in order to do so you will need to modify -your local git installation and follow a very precise set of instructions. -These instructions are documented, along with several useful tips and tricks, in the -[syncing subtree changes][clippy-sync-docs] section in Clippy's Contributing guide. -The instructions are applicable for use with any subtree based tool, just be sure to -use the correct corresponding subtree directory and remote repository. - -The synchronization process goes in two directions: `subtree push` and `subtree pull`. - -A `subtree push` takes all the changes that happened to the copy in this repo and creates commits -on the remote repo that match the local changes. Every local -commit that touched the subtree causes a commit on the remote repo, but -is modified to move the files from the specified directory to the tool repo root. - -A `subtree pull` takes all changes since the last `subtree pull` -from the tool repo and adds these commits to the rustc repo along with a merge commit that moves -the tool changes into the specified directory in the Rust repository. - -It is recommended that you always do a push first and get that merged to the tool master branch. -Then, when you do a pull, the merge works without conflicts. -While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict -resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to -rebase the result of a `git subtree pull`, rebasing merge commits is a bad idea in general. - -You always need to specify the `-P` prefix to the subtree directory and the corresponding remote -repository. If you specify the wrong directory or repository -you'll get very fun merges that try to push the wrong directory to the wrong remote repository. -Luckily you can just abort this without any consequences by throwing away either the pulled commits -in rustc or the pushed branch on the remote and try again. It is usually fairly obvious -that this is happening because you suddenly get thousands of commits that want to be synchronized. - -[clippy-sync-docs]: https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html - -#### Creating a new subtree dependency - -If you want to create a new subtree dependency from an existing repository, call (from this -repository's root directory!) - -``` -git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master -``` - -This will create a new commit, which you may not rebase under any circumstances! Delete the commit -and redo the operation if you need to rebase. - -Now you're done, the `src/tools/clippy` directory behaves as if Clippy were -part of the rustc monorepo, so no one but you (or others that synchronize -subtrees) actually needs to use `git subtree`. - - -### External Dependencies (submodules) - -Building Rust will also use external git repositories tracked using [git -submodules]. The complete list may be found in the [`.gitmodules`] file. Some -of these projects are required (like `stdarch` for the standard library) and -some of them are optional (like [Miri]). - -Usage of submodules is discussed more in the [Using Git -chapter](git.md#git-submodules). - -Some of the submodules are allowed to be in a "broken" state where they -either don't build or their tests don't pass, e.g. the documentation books -like [The Rust Reference]. Maintainers of these projects will be notified -when the project is in a broken state, and they should fix them as soon -as possible. The current status is tracked on the [toolstate website]. -More information may be found on the Forge [Toolstate chapter]. - -Breakage is not allowed in the beta and stable channels, and must be addressed -before the PR is merged. They are also not allowed to be broken on master in -the week leading up to the beta cut. - -[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[`.gitmodules`]: https://github.com/rust-lang/rust/blob/master/.gitmodules -[The Rust Reference]: https://github.com/rust-lang/reference/ -[toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/ -[Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html - -#### Breaking Tools Built With The Compiler - -Rust's build system builds a number of tools that make use of the internals of -the compiler and that are hosted in a separate repository, and included in Rust -via git submodules (such as [Miri]). If these tools break because of your -changes, you may run into a sort of "chicken and egg" problem. These tools rely -on the latest compiler to be built so you can't update them (in their own -repositories) to reflect your changes to the compiler until those changes are -merged into the compiler. At the same time, you can't get your changes merged -into the compiler because the rust-lang/rust build won't pass until those tools -build and pass their tests. - -Luckily, a feature was -[added to Rust's build](https://github.com/rust-lang/rust/issues/45861) to make -all of this easy to handle. The idea is that we allow these tools to be -"broken", so that the rust-lang/rust build passes without trying to build them, -then land the change in the compiler, and go update the tools that you -broke. Some tools will require waiting for a nightly release before this can -happen, while others use the builds uploaded after each bors merge and thus can -be updated immediately (check the tool's documentation for details). Once you're -done and the tools are working again, you go back in the compiler and update the -tools so they can be distributed again. - -This should avoid a bunch of synchronization dances and is also much easier on contributors as -there's no need to block on tools changes going upstream. - -Here are those same steps in detail: - -1. (optional) First, if it doesn't exist already, create a `config.toml` by copying - `config.example.toml` in the root directory of the Rust repository. - Set `submodules = false` in the `[build]` section. This will prevent `x.py` - from resetting to the original branch after you make your changes. If you - need to [update any submodules to their latest versions](#updating-submodules), - see the section of this file about that for more information. -2. (optional) Run `./x.py test src/tools/cargo` (substituting the submodule - that broke for `cargo`). Fix any errors in the submodule (and possibly others). -3. (optional) Make commits for your changes and send them to upstream repositories as a PR. -4. (optional) Maintainers of these submodules will **not** merge the PR. The PR can't be - merged because CI will be broken. You'll want to write a message on the PR referencing - your change, and how the PR should be merged once your change makes it into a nightly. -5. Wait for your PR to merge. -6. Wait for a nightly. -7. (optional) Help land your PR on the upstream repository now that your changes are in nightly. -8. (optional) Send a PR to rust-lang/rust updating the submodule. +## External Dependencies +This sections has moved to ["Using External Repositories"](./external-repos.md). ## Writing Documentation diff --git a/src/external-repos.md b/src/external-repos.md new file mode 100644 index 000000000..795d28af1 --- /dev/null +++ b/src/external-repos.md @@ -0,0 +1,157 @@ +# Using External Repositories + +The `rust-lang/rust` git repository depends on several other repos in the `rust-lang` organization. +There are three main ways we use dependencies: +1. As a Cargo dependency through crates.io (e.g. `rustc-rayon`) +2. As a git subtree (e.g. `clippy`) +3. As a git submodule (e.g. `cargo`) + +As a general rule, use crates.io for libraries that could be useful for others in the ecosystem; use +subtrees for tools that depend on compiler internals and need to be updated if there are breaking +changes; and use submodules for tools that are independent of the compiler. + +## External Dependencies (subtree) + +As a developer to this repository, you don't have to treat the following external projects +differently from other crates that are directly in this repo: + +* [Clippy](https://github.com/rust-lang/rust-clippy) +* [Miri] +* [rustfmt](https://github.com/rust-lang/rustfmt) +* [rust-analyzer](https://github.com/rust-lang/rust-analyzer) + +In contrast to `submodule` dependencies +(see below for those), the `subtree` dependencies are just regular files and directories which can +be updated in tree. However, if possible, enhancements, bug fixes, etc. specific +to these tools should be filed against the tools directly in their respective +upstream repositories. The exception is that when rustc changes are required to +implement a new tool feature or test, that should happen in one collective rustc PR. + +### Synchronizing a subtree + +Periodically the changes made to subtree based dependencies need to be synchronized between this +repository and the upstream tool repositories. + +Subtree synchronizations are typically handled by the respective tool maintainers. Other users +are welcome to submit synchronization PRs, however, in order to do so you will need to modify +your local git installation and follow a very precise set of instructions. +These instructions are documented, along with several useful tips and tricks, in the +[syncing subtree changes][clippy-sync-docs] section in Clippy's Contributing guide. +The instructions are applicable for use with any subtree based tool, just be sure to +use the correct corresponding subtree directory and remote repository. + +The synchronization process goes in two directions: `subtree push` and `subtree pull`. + +A `subtree push` takes all the changes that happened to the copy in this repo and creates commits +on the remote repo that match the local changes. Every local +commit that touched the subtree causes a commit on the remote repo, but +is modified to move the files from the specified directory to the tool repo root. + +A `subtree pull` takes all changes since the last `subtree pull` +from the tool repo and adds these commits to the rustc repo along with a merge commit that moves +the tool changes into the specified directory in the Rust repository. + +It is recommended that you always do a push first and get that merged to the tool master branch. +Then, when you do a pull, the merge works without conflicts. +While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict +resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to +rebase the result of a `git subtree pull`, rebasing merge commits is a bad idea in general. + +You always need to specify the `-P` prefix to the subtree directory and the corresponding remote +repository. If you specify the wrong directory or repository +you'll get very fun merges that try to push the wrong directory to the wrong remote repository. +Luckily you can just abort this without any consequences by throwing away either the pulled commits +in rustc or the pushed branch on the remote and try again. It is usually fairly obvious +that this is happening because you suddenly get thousands of commits that want to be synchronized. + +[clippy-sync-docs]: https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html + +### Creating a new subtree dependency + +If you want to create a new subtree dependency from an existing repository, call (from this +repository's root directory!) + +``` +git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master +``` + +This will create a new commit, which you may not rebase under any circumstances! Delete the commit +and redo the operation if you need to rebase. + +Now you're done, the `src/tools/clippy` directory behaves as if Clippy were +part of the rustc monorepo, so no one but you (or others that synchronize +subtrees) actually needs to use `git subtree`. + + +## External Dependencies (submodules) + +Building Rust will also use external git repositories tracked using [git +submodules]. The complete list may be found in the [`.gitmodules`] file. Some +of these projects are required (like `stdarch` for the standard library) and +some of them are optional (like [Miri]). + +Usage of submodules is discussed more in the [Using Git +chapter](git.md#git-submodules). + +Some of the submodules are allowed to be in a "broken" state where they +either don't build or their tests don't pass, e.g. the documentation books +like [The Rust Reference]. Maintainers of these projects will be notified +when the project is in a broken state, and they should fix them as soon +as possible. The current status is tracked on the [toolstate website]. +More information may be found on the Forge [Toolstate chapter]. + +Breakage is not allowed in the beta and stable channels, and must be addressed +before the PR is merged. They are also not allowed to be broken on master in +the week leading up to the beta cut. + +[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[`.gitmodules`]: https://github.com/rust-lang/rust/blob/master/.gitmodules +[The Rust Reference]: https://github.com/rust-lang/reference/ +[toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/ +[Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html + +### Breaking Tools Built With The Compiler + +Rust's build system builds a number of tools that make use of the internals of +the compiler and that are hosted in a separate repository, and included in Rust +via git submodules (such as [Miri]). If these tools break because of your +changes, you may run into a sort of "chicken and egg" problem. These tools rely +on the latest compiler to be built so you can't update them (in their own +repositories) to reflect your changes to the compiler until those changes are +merged into the compiler. At the same time, you can't get your changes merged +into the compiler because the rust-lang/rust build won't pass until those tools +build and pass their tests. + +Luckily, a feature was +[added to Rust's build](https://github.com/rust-lang/rust/issues/45861) to make +all of this easy to handle. The idea is that we allow these tools to be +"broken", so that the rust-lang/rust build passes without trying to build them, +then land the change in the compiler, and go update the tools that you +broke. Some tools will require waiting for a nightly release before this can +happen, while others use the builds uploaded after each bors merge and thus can +be updated immediately (check the tool's documentation for details). Once you're +done and the tools are working again, you go back in the compiler and update the +tools so they can be distributed again. + +This should avoid a bunch of synchronization dances and is also much easier on contributors as +there's no need to block on tools changes going upstream. + +Here are those same steps in detail: + +1. (optional) First, if it doesn't exist already, create a `config.toml` by copying + `config.example.toml` in the root directory of the Rust repository. + Set `submodules = false` in the `[build]` section. This will prevent `x.py` + from resetting to the original branch after you make your changes. If you + need to [update any submodules to their latest versions](#updating-submodules), + see the section of this file about that for more information. +2. (optional) Run `./x.py test src/tools/cargo` (substituting the submodule + that broke for `cargo`). Fix any errors in the submodule (and possibly others). +3. (optional) Make commits for your changes and send them to upstream repositories as a PR. +4. (optional) Maintainers of these submodules will **not** merge the PR. The PR can't be + merged because CI will be broken. You'll want to write a message on the PR referencing + your change, and how the PR should be merged once your change makes it into a nightly. +5. Wait for your PR to merge. +6. Wait for a nightly. +7. (optional) Help land your PR on the upstream repository now that your changes are in nightly. +8. (optional) Send a PR to rust-lang/rust updating the submodule. + From 6f18c51237954c40523abb0f25a21702f13fcf20 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 25 Mar 2023 19:43:16 -0500 Subject: [PATCH 3/6] 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. --- src/SUMMARY.md | 2 +- src/about-this-guide.md | 38 +++++++ src/contributing.md | 229 +++++++++++++++++++++++++--------------- src/getting-started.md | 193 +++++++-------------------------- 4 files changed, 216 insertions(+), 246 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index ccca3acf5..5eac9a12f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -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) diff --git a/src/about-this-guide.md b/src/about-this-guide.md index 71407854e..8fc2cd6d7 100644 --- a/src/about-this-guide.md +++ b/src/about-this-guide.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`. + _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 diff --git a/src/contributing.md b/src/contributing.md index 8a918a970..47f91bd1f 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -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. - - - -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 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`. - _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 +This section has moved to the ["About this guide"][more-links] chapter. + +[more-links]: ./about-this-guide.md#other-places-to-find-information diff --git a/src/getting-started.md b/src/getting-started.md index 8c00dc6a9..87a5dbbd5 100644 --- a/src/getting-started.md +++ b/src/getting-started.md @@ -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. + +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 From c3610f113cf9044a0317a73404051135c4529d73 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 25 Mar 2023 20:01:25 -0500 Subject: [PATCH 4/6] Link to bug-fix-procedure.md from the contribution procedure section --- src/SUMMARY.md | 2 +- src/bug-fix-procedure.md | 9 ++++++++- src/contributing.md | 27 +++------------------------ 3 files changed, 12 insertions(+), 26 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 5eac9a12f..7c85576ff 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -40,7 +40,7 @@ - [Using Git](./git.md) - [Mastering @rustbot](./rustbot.md) - [Walkthrough: a typical contribution](./walkthrough.md) -- [Bug Fix Procedure](./bug-fix-procedure.md) +- [Procedures for Breaking Changes](./bug-fix-procedure.md) - [Implementing new features](./implementing_new_features.md) - [Stability attributes](./stability.md) - [Stabilizing Features](./stabilization_guide.md) diff --git a/src/bug-fix-procedure.md b/src/bug-fix-procedure.md index 2f5e24716..65881c240 100644 --- a/src/bug-fix-procedure.md +++ b/src/bug-fix-procedure.md @@ -1,4 +1,4 @@ -# Rustc Bug Fix Procedure +# Procedures for Breaking Changes @@ -169,6 +169,13 @@ there were no errors before. #### Crater and crates.io +[Crater] 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 + We should always do a crater run to assess impact. It is polite and considerate to at least notify the authors of affected crates the breaking change. If we can submit PRs to fix the problem, so much the better. diff --git a/src/contributing.md b/src/contributing.md index 47f91bd1f..a96e1e98d 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -83,30 +83,9 @@ 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 +Breaking changes have a [dedicated section][breaking-changes] in the dev-guide. + +[breaking-changes]: ./bug-fix-procedure.md ### Major Changes From 81513ef485683c6ddfb1dd61a391b38ec0ad7b7d Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 25 Mar 2023 20:04:18 -0500 Subject: [PATCH 5/6] Remove duplicate section on new features in CONTRIBUTING.md --- src/contributing.md | 24 ++---------------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/src/contributing.md b/src/contributing.md index a96e1e98d..0b4fa5c56 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -58,28 +58,8 @@ channels: stable, beta, and nightly. 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) +See [this chapter on implementing new features](./implementing_new_features.md) for more +information. ### Breaking Changes From 5ce68b8e18a2db1a613e1ab80b4d60a427c53371 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sat, 25 Mar 2023 20:11:38 -0500 Subject: [PATCH 6/6] add a few more TOC sections --- src/bug-fix-procedure.md | 2 +- src/building/how-to-build-and-run.md | 2 ++ src/building/new-target.md | 2 ++ src/building/suggested.md | 2 ++ src/contributing.md | 2 ++ src/implementing_new_features.md | 2 ++ src/rustdoc.md | 8 +++++--- 7 files changed, 16 insertions(+), 4 deletions(-) diff --git a/src/bug-fix-procedure.md b/src/bug-fix-procedure.md index 65881c240..e69ce48f9 100644 --- a/src/bug-fix-procedure.md +++ b/src/bug-fix-procedure.md @@ -174,7 +174,7 @@ 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 +[Crater]: ./tests/crater.md We should always do a crater run to assess impact. It is polite and considerate to at least notify the authors of affected crates the breaking change. If we can diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 564136453..ffb93f6b2 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -1,5 +1,7 @@ # How to build and run the compiler + + The compiler is built using a tool called `x.py`. You will need to have Python installed to run it. diff --git a/src/building/new-target.md b/src/building/new-target.md index f999a9472..629445be6 100644 --- a/src/building/new-target.md +++ b/src/building/new-target.md @@ -4,6 +4,8 @@ These are a set of steps to add support for a new target. There are numerous end states and paths to get there, so not all sections may be relevant to your desired goal. + + ## Specifying a new LLVM For very new targets, you may need to use a different fork of LLVM diff --git a/src/building/suggested.md b/src/building/suggested.md index c7aab9a48..3049d87db 100644 --- a/src/building/suggested.md +++ b/src/building/suggested.md @@ -3,6 +3,8 @@ The full bootstrapping process takes quite a while. Here are some suggestions to make your life easier. + + ## Installing a pre-push hook CI will automatically fail your build if it doesn't pass `tidy`, our diff --git a/src/contributing.md b/src/contributing.md index 0b4fa5c56..549c18cc4 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -1,5 +1,7 @@ # Contribution Procedures + + ## Bug Reports While bugs are unfortunate, they're a reality in software. We can't fix what we diff --git a/src/implementing_new_features.md b/src/implementing_new_features.md index 9bd853080..946637d29 100644 --- a/src/implementing_new_features.md +++ b/src/implementing_new_features.md @@ -1,5 +1,7 @@ # Implementing new features + + When you want to implement a new significant feature in the compiler, you need to go through this process to make sure everything goes smoothly. diff --git a/src/rustdoc.md b/src/rustdoc.md index d58b27bb7..cbe5e8b1f 100644 --- a/src/rustdoc.md +++ b/src/rustdoc.md @@ -1,8 +1,5 @@ # Rustdoc overview -`rustdoc` uses `rustc` internals (and, of course, the standard library), so you -will have to build the compiler and `std` once before you can build `rustdoc`. - `rustdoc` lives in-tree with the compiler and standard library. This chapter is about how it works. For information about Rustdoc's features and how to use them, see @@ -12,6 +9,11 @@ For more details about how rustdoc works, see the [Rustdoc internals]: ./rustdoc-internals.md + + +`rustdoc` uses `rustc` internals (and, of course, the standard library), so you +will have to build the compiler and `std` once before you can build `rustdoc`. + Rustdoc is implemented entirely within the crate [`librustdoc`][rd]. It runs the compiler up to the point where we have an internal representation of a crate (HIR) and the ability to run some queries about the types of items. [HIR]