[docs] Improve upgrade experience from Material UI v4

[oliviertassinari]

I have just noticed how broken the migration experience from v4 is.

Open https://v4.mui.com/components/container/ 🙈.

• We say "migrate to v5, go to mui.com". meaning v5 is called MUI.
• We don't say anything on how to migrate", good luck

[danilo-leal]

Looks good to me! 🤙

---

Tangentially, though, the MUI = Material UI confusion, as far as versioning and what it means, is still very tangled to me. Take the "Preparing for v6" issue (#30660) — that's like, Material UI v6, right? It's not mentioned in the title nor do we use the "package: material-ui" label there, which slightly indicates it's about something else more all-encompassing. Here, however, we talk about migrating from Material's v4 to v5, so I assume v6 there is, in fact, the next Material major. But then, why are we talking about Base UI and Joy UI stuff on the Material UI v6 issue? Aren't they independent? etc. I can see how we'd say "it's actually the Core repo's v6" but then it would contradict this PR 😅 Anyway, not to spin out a big thread out of this, but just pointing this out because I thought it was illustrative!

[oliviertassinari]

"Preparing for v6" issue (#30660)

@danilo-leal For me, this issue is about working on "MUI Core" v6, meaning coordinating Joy UI, Base UI, Material UI, MUI System to 1. all work well together and 2. without one doing a local optimization that goes against the global optimization. It could indeed be split into 4 different issues.

but then it would contradict this PR

The way I see it, if someone using Material UI v4 first cares about migrating to Material UI v5 to stay up to date, he might not care about the extra projects that come alongside it.

[danilo-leal]

The root issue for me is that we use "MUI Core v6" and "Material UI v6" interchangeably, deepening the confusion of MUI = Material UI. This is a larger versioning convo (like, why brand new packages/products are starting from v5?). (And I'd probably change the issue title if we're referring to the Core products to alleviate it a bit).

[oliviertassinari]

Deploy live https://v4.mui.com/components/container/

---

like, why brand new packages/products are starting from v5?

@danilo-leal The value could be to communicate clearly which versions are compatible together, and which versions use the same conventions. Similar to Qt whole stack being a single version: https://www.qt.io/product/features.

For example, Radix starts to feel a bit strange, they have Radix Themes, Radix Primitives, Radix Icons, Radix Colors now. Replace Radix with MUI, it's pretty close to what we do. They could have kept Radix for the headless UI components only. They take the risk of confusing their users but they sell the value of one ecosystem that works well together.

I wonder if we are not overlearning. We might be over-indexing the value of isolating product names and discounting too much the value of a stable version, and the need for great execution.

Maybe instead of investing energy in trying to not inherit the reputation of Material UI, we should go all-in in improving it.