[docs] Add "Migration" section to sidebar and revise v4-v5 content

[mapache-salvaje]

https://deploy-preview-32740--material-ui.netlify.app/material-ui/migration/migration-v4/
https://deploy-preview-32740--material-ui.netlify.app/material-ui/migration/v5-style-changes/
https://deploy-preview-32740--material-ui.netlify.app/material-ui/migration/v5-component-changes/
https://deploy-preview-32740--material-ui.netlify.app/material-ui/migration/migrating-from-jss/
https://deploy-preview-32740--material-ui.netlify.app/material-ui/migration/troubleshooting/

This PR addresses the ongoing need to get more developers to migrate to Material UI v5.

I am proposing that we add a new section to the Material UI docs sidebar for "Migration" to help draw attention to these docs:

In an effort to make the v4-v5 migration guide more readable, I have split the content up into multiple pages. I have also done some copy editing throughout.

I have attempted to make it more clear that you do not need to migrate away from JSS to start using v5, as well as the fact that you need to move to v5 for React 18.

I don't intend to make any changes to the earlier migration guides, other than to move them to this new section.

To do:

• add Migration to sidebar
• move Migration pages
• split v4-v5 content
• revise v4-v5 content
  • Migration
  • Breaking changes - styles and themes
  • Breaking changes - components
  • JSS
  • Troubleshooting
• find and fix broken links to these pages

[mui-bot]

No bundle size changes

Generated by 🚫 dangerJS against 3ff10dc

[siriwatknp]

I am proposing that we add a new section to the Material UI docs sidebar for "Migration" to help draw attention to these docs:

Couldn't agree more 👍

In an effort to make the v4-v5 migration guide more readable, I am going to split the content up into multiple pages. I will also do some copy editing throughout.

Your proposal looks fantastic!

[mapache-salvaje]

I have added ✅ emoji next to all of the breaking changes that are handled by codemods. I think this makes it much easier to navigate through these docs, and to use the right side nav bar to quickly skim through the content. I will most likely remove the redundant :::success callouts in a later commit.

I have also opted to split the breaking changes into two separate pages to make them more user-friendly.

This is turning into a much bigger project than I anticipated. 😅 There is so much content here!

[danilo-leal]

Woof, this is so good! Fantastic work, Sam 👏

[oliviertassinari]

It's so much better with the reorganization 🔥😍, great execution!

Things that I have noticed:

1. Are we sure about the side nav order? Intuitively, I would imagine Migration to be at the bottom:

2. I have fixed some of the wrong git diff layouts, but there are more, I gave up 😁.
3. I wonder if we didn't go too much into the details of the breaking changes, it's overwhelming. We never went as much in the details in the past. If it's not about the level of details, then it's about the number. We would likely want to enforce a maximum limit on the number of breaking changes per release. v4 -> v5 might be a good reference to what should be the absolute maximum cc @mnajdova oops 🙃

[mnajdova]

We would likely want to enforce a maximum limit on the number of breaking changes per release. v4 -> v5 might be a good reference to what should be the absolute maximum cc @mnajdova oops 🙃

@oliviertassinari I would say we should never do that many breaking changes ever again (not to consider this absolute maximum :)) I almost think it would have been best if we did two major releases in a year (one focusing only on the styling solution changes and another one on the API changes/bug fixes). But anyway, it is late for that kind of discussion now.

[mapache-salvaje]

1. Are we sure about the side nav order? Intuitively, I would imagine Migration to be at the bottom:

I don't have any strong feelings about the order, so I'm cool with moving it to the bottom. 👍

[mnajdova]

Looks awesome! Great execution Sam!