Hm, so I think this is good, but I'm not sure it belongs in general documentation like this.

I think it might be worth it to create two separate documents describing bootstrapping: one for users who want to understand what different flags etc do, and one for developers of bootstrap itself, who want to know about details like this. ISTM that whether we assemble the compiler or not is to some extent an implementation detail, not something I would expect us to document so prominently in general documentation.

So, this is something I've been wanting to bring up for a while - although in an ideal world you wouldn't have to know about bootstrap internals, in practice you have to. If we don't document Assemble, then it makes no sense that x.py build --stage 0 compiler/rustc doesn't create stage1/rustc; it just seems like a bug. It's a leaky abstraction.

Hm, I think I disagree that you "in practice have to." (Bugs aside, of which there are not too many, and we're fixing them over time).

The bug there seems fixable -- I would be happy to take a PR or it can get added to the (endless) list of things I need to look at :) But for now yes we can merge this to improve docs while the bug exists.

Sounds good to me :)