Explain how to work with subrepos

1 files changed, 47 insertions, 2 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2843944b2e1..69ce9dae5aa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -188,7 +188,53 @@ with one another are rolled up.
 Speaking of tests, Rust has a comprehensive test suite. More information about
 it can be found [here][rctd].
 
-### External Dependencies
+### External Dependencies (subrepo)
+
+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:
+
+* none so far, see https://github.com/rust-lang/rust/issues/70651 for more info
+
+They are just regular files and directories. This is in contrast to `submodule` dependencies
+(see below for those).
+
+If you want to synchronize or otherwise work with subrepos, install the `git subrepo` command via
+instructions found at https://github.com/ingydotnet/git-subrepo
+
+#### Synchronizing a subrepo
+
+There are two synchronization directions: `subrepo push` and `subrepo pull`. Both operations create
+a synchronization commit in the rustc repo.
+This commit is very important in order to make future synchronizations work.
+Do not rebase this commit under any circumstances.
+Prefer to merge in case of conflicts or redo the operation if you really need to rebase.
+
+A `git subrepo push src/tools/clippy`
+takes all the changes that
+happened to the copy in this repo and creates commits on the remote repo that match the local
+changes (so every local commit that touched the subrepo causes a commit on the remote repo).
+
+A `git subrepo pull src/tools/clippy` takes all changes since the last `subrepo pull` from the clippy
+repo and creates a single commit in the rustc repo with all the changes.
+
+#### Creating a new subrepo dependency
+
+If you want to create a new subrepo dependency from an existing repository, call (from this
+repository's root directory!!)
+
+```
+git subrepo clone https://github.com/rust-lang/rust-clippy.git src/tools/clippy
+```
+
+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 subrepos) needs to have `git subrepo`
+installed.
+
+
+### External Dependencies (submodules)
 
 Currently building Rust will also build the following external projects:
 
@@ -221,7 +267,6 @@ before the PR is merged.
 
 Rust's build system builds a number of tools that make use of the
 internals of the compiler. This includes
-[Clippy](https://github.com/rust-lang/rust-clippy),
 [RLS](https://github.com/rust-lang/rls) and
 [rustfmt](https://github.com/rust-lang/rustfmt). If these tools
 break because of your changes, you may run into a sort of "chicken and egg"