add some instructions to fix toolstate (#446)

1 files changed, 28 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md
index 064f80c6e4d..fc9a06a8c20 100644
--- a/src/doc/rustc-dev-guide/README.md
+++ b/src/doc/rustc-dev-guide/README.md
@@ -41,3 +41,31 @@ be found.
 
 You will need `mdbook` version `>= 0.2`. `linkcheck` will be run automatically
 when you run `mdbook build`.
+
+## How to fix toolstate failures
+
+1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4
+
+2. The commit contains a link to the PR that caused the breakage. e.g. https://github.com/rust-lang/rust/pull/64321
+
+3. If you go to that PR's thread, there is a post from bors with a link to the CI status: https://github.com/rust-lang/rust/pull/64321#issuecomment-529763807
+
+4. Follow the check-azure link to get to the Azure website for that build: https://dev.azure.com/rust-lang/e71b0ddf-dd27-435a-873c-e30f86eea377/_build/results?buildId=7780
+
+5. There will be approximately 1 billion different jobs for the build. They are for different configurations and platforms. The rustc-guide build only runs on the Linux x86_64-gnu-tools job. So click on that job in the list, which is about 60% down in the list.
+
+6. Click the Run build step in the job to get the console log for the step.
+
+7. Click on the log and Ctrl-f to get a search box in the log
+
+8. Search for rustc-guide. This gets you to the place where the links are checked. It is usually ~11K lines into the log
+
+9. Look at the links in the log near that point in the log
+
+10. Fix those links in the rustc-guide (by making a PR in the rustc-guide repo)
+
+11. Make a PR on the rust-lang/rust repo to update the rustc-guide git submodule in src/docs/rustc-guide
+
+12. Wait for PR to merge
+
+Voila!