Miri subtree instructions

CONTRIBUTING.md

@@ -275,3 +275,59 @@ see <https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html>.
 
 With this, you should now have a working development setup! See
 [above](#building-and-testing-miri) for how to proceed working on Miri.
+
+### Syncing the miri subtree
+
+Note: Never rebase a subtree sync (in either direction). Always redo the operation.
+
+All of these operations happen *on a checkout of the rustc repo*. At no time do you
+even need a checkout of the miri repo or run any commands in it. 
+
+#### Moving changes from the rustc repo to the miri repo
+
+One time setup:
+
+Add your own miri fork as `miri-your-fork` to your rustc checkout:
+
+```
+git remote add miri-your-fork git@github.com:your-name/miri.git
+```
+
+Every time:
+
+Note: the first time you run this, `git subtree` builds a cache and this command may thusly take an hour or so.
+
+```
+ulimit -Ss 1000000
+wget https://raw.githubusercontent.com/gitgitgadget/git/fe2e4819b869725f870cd3ce99f1f8150fe17dc1/contrib/subtree/git-subtree.sh
+sh git-subtree.sh push --prefix src/tools/miri/ miri-your-fork miri-subtree-sync
+rm git-subtree.sh
+```
+
+Now you'll have a branch called `miri-subtree-sync` in your miri fork that you can use to open a PR to miri.
+Do not rebase this branch. If there are conflicts with the miri repo, you need to use the merge strategy, even if this
+is otherwise not permitted for other PRs to the miri repo.
+
+#### Moving changes from the miri repo to the rustc repo
+
+One time setup:
+
+Add the main miri repo as `miri` to your rustc checkout:
+
+```
+git remote add miri https://github.com/rust-lang/miri.git
+```
+
+Every time:
+
+```
+ulimit -Ss 1000000
+wget https://raw.githubusercontent.com/gitgitgadget/git/fe2e4819b869725f870cd3ce99f1f8150fe17dc1/contrib/subtree/git-subtree.sh
+sh git-subtree.sh pull --prefix src/tools/miri/ miri master
+rm git-subtree.sh
+```
+
+Now your currently checked out branch has a new merge commit that pulls in the miri changes. Use this to open a PR
+against the rustc repo.
+Do not rebase this branch. If there are conflicts with the rustc repo, you need to use the merge strategy, even if this
+is otherwise not permitted for other PRs to the rustc repo.