Documenting the process for when rustfmt/rls break

[sunjay]

DO NOT MERGE YET

I'm documenting what to do when rustfmt or rls break because of your changes. I'm currently going through this and will keep adding more as I figure out what all the steps are. This first commit is based on @alexcrichton's comment on my original PR.

Rendered

Reviews are welcome, but as I mentioned, I will be revising this as I go.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @aturon (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[sunjay]

I added a section about updating submodules (specifically rustfmt).

The process for updating rustfmt is quite involved because of the way everything is configured. This section covers the steps for updating rustfmt and rationale behind them.

[sunjay]

I'm still largely new to this codebase, so please help me by reviewing this and making sure it's correct! 😄

[alexcrichton]

I've recently opened #45243 which is where I hope to enable these steps being much shorter where basically it looks like just configuring the rls/rustfmt to "broken", landing the change in rust-lang/rust, wait for a nightly, then go update rls/rustfmt, then come back and update rust-lang/rust.

That way it should avoid a bunch of synchronization dances and also be much easier on contributors as there's no need to block on rls/rustfmt changes going upstream.

[sunjay]

@alexcrichton That's awesome! I'd be happy to update these instructions with the new steps. When you have a chance and that PR is ready, could you give me an idea of what the new steps should be? I'll then do the same thing I did with your old instructions and format and add them to this PR. 😄

[alexcrichton]

@sunjay sure, it'd look like this:

1. (optional) 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. (optional) Run ./x.py test src/tools/rustfmt (substituting the submodule that broke for rustfmt). Fix any errors in the submodule (and possibly others)
3. (optional) Make commits for your changes and send them to upstream repositories as a PR.
4. (optional) Maintainers of these submodules will not merge the PR. The PR can't be merged because CI will be broken. You'll want to write a message on the PR referencing your change, and how the PR should be merged once your change makes it into a nightly.
5. Update src/tools/toolstate.toml to indicate that the tool in question is "broken", that will disable building it on CI.
6. Commit the changes to src/tools/toolstate.toml, do not update submodules in your commit, and then update the PR you have for rust-lang/rust.
7. Wait for your PR to merge.
8. Wait for a nightly
9. (optional) Help land your PR on the upstream repository now that your changes are in nightly.
10. (optional) Send a PR to rust-lang/rust updating the submodule, reverting src/tools/toolstate.toml back to a "building" or "testing" state.

[sunjay]

@alexcrichton This is now up to date with the latest instructions from your comment above. I think these instructions look great and hopefully they'll be a lot of help to someone in the future! Just a reminder that this PR adds two sections: Breaking Tools Built With The Compiler and Updating submodules. Both sections are the result of my adventures with #44766 and are a product of your very detailed comments with instructions which I used to accomplish everything I did in that PR. 😄

I really hope these come in handy for future people working on these parts of the compiler! :)

[alexcrichton]

@bors: r+ rollup

Looks great to me, thanks @sunjay!

[bors]

📌 Commit 790604a has been approved by alexcrichton