user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

sembr src/external-repos.md

Browse source
This commit is contained in:
Tshepang Mbambo 2026-01-12 20:08:03 +02:00
parent ffe359fe2b
commit 52a5023e76
1 changed files with 27 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

48
src/doc/rustc-dev-guide/src/external-repos.md
View file

@ -30,8 +30,8 @@ The following external projects are managed using some form of a `subtree`:
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
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.
`subtree` dependencies are currently managed by two distinct approaches:
@ -51,7 +51,9 @@ implement a new tool feature or test, that should happen in one collective rustc
### Josh subtrees
The [josh] tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories. Specific tooling is required to work with josh. We provide a helper [`rustc-josh-sync`][josh-sync] tool to help with the synchronization, described [below](#synchronizing-a-josh-subtree).
The [josh] tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories.
Specific tooling is required to work with josh.
We provide a helper [`rustc-josh-sync`][josh-sync] tool to help with the synchronization, described [below](#synchronizing-a-josh-subtree).
### Synchronizing a Josh subtree
@ -69,8 +71,7 @@ changes from the subtree to rust-lang/rust) are performed from the subtree repos
switch to its repository checkout directory in your terminal).
#### Performing pull
1) Checkout a new branch that will be used to create a PR into the subtree
2) Run the pull command
1) Checkout a new branch that will be used to create a PR into the subtree 2) Run the pull command
```
rustc-josh-sync pull
```
@ -97,7 +98,8 @@ If you want to migrate a repository dependency from `git subtree` or `git submod
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
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
@ -108,8 +110,8 @@ 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
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`
@ -119,14 +121,17 @@ 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 default branch of the tool.
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
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
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
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
@ -140,8 +145,8 @@ 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.
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
@ -149,24 +154,25 @@ 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
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 `src/doc/book`).
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].
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 `main` in
the week leading up to the beta cut.
before the PR is merged.
They are also not allowed to be broken on `main` 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/HEAD/.gitmodules