[Grid2] Rollout plan

[oliviertassinari]

Summary

We recently made Grid v2 stable, #43054 so now it's time to look at the rollout plan, effectively to get completely get rid of the old one.

A possible action plan:

• 0. Fix the migration experience
• 0.a. There is no clear warning when doing <Grid2 item>. It says:

I think we need a custom prop type instead, that clearly explain that this is a Grid v1 prop, that you can now remove the prop.

• 0.b. There is no clear prop-type warning when doing <Grid2 xs={12}>. The attribute gets silently applied to the DOM:

• 0.c. I got the impression that the migration guide was started but not finished: https://mui.com/material-ui/migration/migration-grid-v2/. I couldn't rely a lot on it. The problems I saw:

  • It doesn't talk about what to do with the xs, sm, etc. props.
  • It references older version of Material UI before newer ones, isn't the order inverted?
  • It doesn't have a full set of step to go from Grid to Grid2 when using Material UI v6
  • In https://mui.com/material-ui/migration/migration-grid-v2/#why-you-should-migrate we could list the value of not using negative margins: e.g. https://github.com/mui/mui-private/pull/685

• 1. Update the h1 in https://next.mui.com/material-ui/react-grid/ to mention deprecated, so Google and Algolia search results are clear

• 2. Reexport Grid v2 from @mui/system/Grid2 getting one step closer to move everyone imports from @mui/material to mui/system [RFC] Remove @mui/material default theme and @mui/system, @pigment-css/react reexports #40594

• 3. Migrate all the MUI codebase to the Grid v2

• 4. Introduce a deprecation warning when using Grid v1 [material-ui] Deprecate system props #42259

• 5. In the next major swap the implementation for the Grid namespace, put the deprecated Grid v1 into the exported GridLegacy namespace

• 6. In the major after that next major, remove GridLegacy.

Motivation

Simplicity

[DiegoAndai]

The plan looks good overall, @oliviertassinari 👌🏼

The only step I'm not sure of is:

2. Reexport Grid v2 from @mui/system/Grid2 getting one step closer to move everyone imports from @mui/material to mui/system [RFC] Remove @mui/material default theme and @mui/system, @pigment-css/react reexports #40594

I don't know the long-term vision for the system package, and we need to solve that before setting the goal of moving everyone to import Grid from it. This is not the issue to discuss this. @aarongarciah and @colmtuite should probably lead the discussion.

[oliviertassinari]

The only step I'm not sure of is: 2. Reexport Grid v2 from […]

@DiegoAndai Alright, I have removed that step.

---

Since this new Grid has been here for about 6 months but we haven't completed the work, and since we can't start anything new until we finish what we started (so we only start things we have the bandwidth to see through), I have tried to help a bit with step 3. in https://github.com/mui/mui-private/pull/685.

I have struggled a bit, it was frustrating, I think that we have clear opportunities to turn this into a great DX. I believe we need to do:

• a. There is no clear warning when doing <Grid2 item>. It says:

I think we need a custom prop type instead, that clearly explain that this is a Grid v1 prop, that you can now remove the prop.

• b. There is no clear prop-type warning when doing <Grid2 xs={12}>. The attribute gets silently applied to the DOM:

• c. I got the impression that the migration guide was started but not finished: https://mui.com/material-ui/migration/migration-grid-v2/. I couldn't rely a lot on it. The problems I saw:

  • It doesn't talk about what to do with the xs, sm, etc. props.
  • It references older version of Material UI before newer ones, isn't the order inverted?
  • It doesn't have a full set of step to go from Grid to Grid2 when using Material UI v6
  • In https://mui.com/material-ui/migration/migration-grid-v2/#why-you-should-migrate we could list the value of not using negative margins: e.g. https://github.com/mui/mui-private/pull/685

[siriwatknp]

@DiegoAndai What's the checkboxes PR will cross?

I can help with the one that the PR hasn't addressed.

[DiegoAndai]

Hey @siriwatknp, #45304 will complete 0.a, 0.b, and 0.c. I've already started working on the other steps but need #45304 to be merged first. I'll let you know if I need help with any of these 👍🏼

[DiegoAndai]

I'll move this issue out of the v7 milestone and into the v8 one. All work for v7 has been completed, the only thing missing from the tasks is to remove GridLegacy on v8.