Rollup merge of #70970 - eddyb:trait-vs-impl-mismatch, r=oli-obk

[rust.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index be31cc26da531174aad1329d5e94ff53249e2e13..051f5af7bc105cd53d393093ef45a15de27c248c 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -196,28 +196,49 @@ 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).
+(see below for those). Only tool authors will actually use any operations here.
 
 #### Synchronizing a subtree
 
 There are two synchronization directions: `subtree push` and `subtree pull`.
 
-A `git subtree push -P src/tools/clippy`
+```
+git subtree push -P src/tools/clippy git@github.com:your-github-name/rust-clippy sync-from-rust
+```
+
 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 subtree causes a commit on the remote repo).
+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.
+
+Make sure to not pick the `master` branch on the tool repo, so you can open a normal PR to the tool
+to merge that subrepo push.
+
+```
+git subtree pull -P src/tools/clippy https://github.com/rust-lang/rust-clippy master
+```
+
+takes all changes since the last `subtree pull` from the tool repo
+repo and adds these commits to the rustc repo + a merge commit that moves the tool changes into
+the specified directory in the rust repository.
 
-A `git subtree pull -P src/tools/clippy` takes all changes since the last `subtree pull` from the clippy
-repo and creates a single commit in the rustc repo with all the changes.
+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 specifiy the `-P` prefix to the subtree directory. If you specify the wrong directory
-you'll get very fun merges that try to push the wrong directory to the remote repository. Luckily you
-can just abort this without any consequences.
+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.
 
 #### 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!!)
+repository's root directory!)
 
 ```
 git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
@@ -227,7 +248,7 @@ This will create a new commit, which you may not rebase under any circumstances!
 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) needs actually use `git subtree`.
+monorepo, so no one but you (or others that synchronize subtrees) actually needs to use `git subtree`.
 
 
 ### External Dependencies (submodules)