From bd4907d534a1894e28a1f3cf672022e29eabf194 Mon Sep 17 00:00:00 2001 From: Sunjay Varma Date: Sat, 7 Oct 2017 21:53:43 -0400 Subject: [PATCH] Documenting the process for when rustfmt/rls breakk because of your changes --- CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a86742d7bd4..c6c62a8c7b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -363,6 +363,44 @@ outside the submodule. It can also be more convenient during development to set `submodules = false` in the `config.toml` to prevent `x.py` from resetting to the original branch. +#### Breaking rustfmt or rls + +Rust's build system also builds the +[RLS](https://github.com/rust-lang-nursery/rls) +and [rustfmt](https://github.com/rust-lang-nursery/rustfmt). If these tools +break because of your changes, you may run into a sort of "chicken and egg" +problem. Both tools rely on the latest compiler to be built so you can't update +them until the changes you are making to the compiler land. In the meantime, you +can't land your changes to the compiler because the build won't pass until those +tools are fixed. + +That means that, in the default state, you can't update the compiler without +fixing rustfmt and rls first. + +When this happens, follow these steps: + +1. First, if it doesn't exist already, create a `config.toml` by copying + `config.toml.example` in the root directory of the Rust repository. + Set `submodules = false` in the `[build]` section. This will prevent `x.py` + from resetting to the original branch after you make your changes. +2. Run `./x.py test src/tools/rustfmt`. Fix any errors in the submodule itself + (the `src/tools/rustfmt` directory) until it works. +3. Run `./x.py test src/tools/rls`. Fix any errors in the submodule itself + (the `src/tools/rls` directory) until it works. +4. Make a commit for `rustfmt`, if necessary, and send a PR to the master + branch of rust-lang-nursery/rustfmt +5. Do the same, if necessary for the RLS +6. A maintainer of rls/rustfmt will **not** merge the PR. The PR can't be + merged because CI will be broken. Instead a new branch will be created, + and the PR will be pushed to the branch (the PR is left open) +7. On your branch, update the rls/rustfmt submodules to these branches +8. Commit the changes, update your PR to rust-lang/rust +9. Wait for the branch to merge +10. Wait for a nightly +11. A maintainer of rls/rustfmt will merge the original PRs to rls/rustfmt +12. Eventually the rls/rustfmt submodules will get re-updated back to the + master branch + ## Writing Documentation [writing-documentation]: #writing-documentation