From 04c8191719761dd8617fb84a86fe114ed7ac6eab Mon Sep 17 00:00:00 2001 From: Oliver Scherer Date: Wed, 1 Apr 2020 13:19:11 +0200 Subject: [PATCH] Explain how to work with subrepos --- CONTRIBUTING.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file 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"