Skip to content

Link to forge instead of duplicating toolstate info #1664

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 9, 2023
Merged

Link to forge instead of duplicating toolstate info #1664

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0ee0f3e
fix incorrect miri mentions in "External Repos" chapter
jyn514 Apr 6, 2023
a3b2cc8
Remove detailed toolstate section
jyn514 Apr 8, 2023
72e06b0
document that it's rare for books to break
jyn514 Apr 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 5 additions & 49 deletions src/external-repos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ differently from other crates that are directly in this repo:
* [rustfmt](https://github.com/rust-lang/rustfmt)
* [rust-analyzer](https://github.com/rust-lang/rust-analyzer)

[Miri]: https://github.com/rust-lang/miri

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
Expand Down Expand Up @@ -88,17 +90,17 @@ subtrees) actually needs to use `git subtree`.
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]).
some of them are optional (like `src/doc/book`).

Usage of submodules is discussed more in the [Using Git
chapter](git.md#git-submodules).
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].
In practice, it is very rare for documentation to have broken toolstate.

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
Expand All @@ -109,49 +111,3 @@ the week leading up to the beta cut.
[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.