I think @mark-i-m and @spastorino are also planning to make a PR to rustc-dev-guide using the diagram I linked: https://github.com/rust-lang/rustc-dev-guide/files/5024984/diagram.pdf

👍 to the idea of looking for more accurate names. In case this is a good idea for others, I'd suggest to deprecate/remove --stage X usage.

I don't personally see this as helpful, but then again I feel that I have a pretty good grasp as to which arguments to pass when (understandably, given that I've been involved with rustbuild/bootstrap for ~4 years now), so maybe I'm not the best judge.

It does feel like adding more names would just increase people's confusion, especially if (like they do now) they all map to the same underlying options in bootstrap.

It feels like there is inherent complexity here that you need to understand if you pass --stage at all -- but the expectation after the x.py defaults change is that no one should need to do so, right? (Or maybe not quite, and we need to change some more defaults?) My hope is that the inherent complexity with staging can be hidden away from users behind good defaults and then we don't need to try and explain it.

It does feel like adding more names would just increase people's confusion, especially if (like they do now) they all map to the same underlying options in bootstrap.

I think the very fact that they map to the same underlying options is confusing. If you run x.py build --stage 1 src/rustc, that builds a different rustc from x.py test --stage 1 (ignoring *-fulldeps).

It feels like there is inherent complexity here that you need to understand if you pass --stage at all -- but the expectation after the x.py defaults change is that no one should need to do so, right? (Or maybe not quite, and we need to change some more defaults?) My hope is that the inherent complexity with staging can be hidden away from users behind good defaults and then we don't need to try and explain it.

Well, sort of. 1 for passing --stage less, but at some point you'll need to pass it, at which point you need to understand what it means. I think the current status where --stage means something different depending on the subcommand is really non-intuitive and we should make that difference as clear as possible. Or in other words, I don't think all of the complexity around --stage is necessarily inherent, and it might make sense eventually to have --run-stage and --build-stage map to different underlying things.

Also, note that until intra-doc links are more stabilized there is no good default for doc, either you have to compile all of rustdoc instead of using beta or you don't get the latest fixes. So there's a lot of people using doc --stage 1 currently.

You're not wrong that this is perhaps confusing, but it doesn't seem like adding 2 new terms would be helpful here. If we want to change this such that staging always refers to the rustc, for example, then that seems like something to explore. But just adding options doesn't feel like a win, especially if we're going to end up wanting to change the meaning of those options down the line.

Insofar as "you will need to pass --stage" -- I feel like this is a failing if true. Similar to how Rust as a whole tries to make it such that the vast majority of code won't need to use unsafe, the vast majority of people shouldn't need to use --stage. And, sure, if you do need to use it will take you a bit to understand the model, and maybe the model isn't entirely consistent right now; I am on board with updating our model to be more consistent. But -- IMO -- it is true that the current model can be understood; certainly we don't have good documentation, and maybe there's rough edges that can be smoothed out, but it does seem fixable.

Also, note that until intra-doc links are more stabilized there is no good default for doc, either you have to compile all of rustdoc instead of using beta or you don't get the latest fixes. So there's a lot of people using doc --stage 1 currently.

Note that stabilization here is irrelevant, just the implementation gaining functionality is relevant. And yes, it is true that when significant functionality is added to rustdoc and that functionality is used in our documentation without cfg(bootstrap) we lose the ability to build with --stage 0, which is otherwise a good default. This is a trade-off we face with the use of any feature not present in the beta compiler, and it is up to the teams whether they wish to hurt the default experience for folks trying to write documentation for the standard library.

it doesn't seem like adding 2 new terms would be helpful here

Maybe it would help if you explained your mental model a little more? In my mind, since test --stage 1 and build --stage 1 src/rustc have different behaviors, that means they're different concepts. But maybe in your mind that's consistent - if so it would be great to explain why so we can teach that to new contributors.

If we want to change this such that staging always refers to the rustc, for example, then that seems like something to explore.

I've met with a lot of resistance on this front (mostly from @eddyb :P) - and I'm not sure it's unwarranted, it's not just changing the defaults like #73964 but changing the whole mental model. So I thought that this would be good in the meantime to make it clearer what the options do currently, without changing behavior. FWIW the new arguments correspond to the new mental model I suggested for using the same rustc: I proposed that everything uses --run-stage instead of some commands using --link-stage and others using --run-stage.

when significant functionality is added to rustdoc and that functionality is used in our documentation without cfg(bootstrap) we lose the ability to build with --stage 0, which is otherwise a good default. This is a trade-off we face with the use of any feature not present in the beta compiler

Getting a little off-topic, but that's not exactly what's going on with intra-doc links. This isn't just using a shiny feature, it's fixing links in core that have been broken for years. The difference between the old behavior and the new is that the new links fail noisily with --stage 0, where they used to fail silently (and were ignored by the linkchecker).

Related: rust-lang/rustc-dev-guide#843. I think this should wait until the discussion there is resolved at a minimum, and then if it turns out this is a useful mental model we could consider adding these aliases.

I'm just going to close this in that case, I don't think keeping the PR open helps personally.