[material-ui][docs] Add first batch of v6 migration #42242

siriwatknp · 2024-05-14T19:15:13Z

I have followed (at least) the PR section of the contributing guide.

Preview: https://deploy-preview-42242--material-ui.netlify.app/material-ui/migration/migration-v5/

Out of scope

Pigment CSS migration (likely to be added after beta release)

docs/data/material/migration/migration-v5/migration-v5.md

mui-bot · 2024-05-14T19:17:57Z

Netlify deploy preview

docs/data/material/migration/migration-v5/migration-v5.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against ab5f2e4

docs/data/material/migration/migration-v5/migration-v5.md

…igration-v6

DiegoAndai · 2024-05-17T16:34:37Z

Hey @siriwatknp! I merged #42194. I'll complete the deprecations section as soon as possible.

docs/data/material/migration/migration-v5/migration-v5.md

…igration-v6

mnajdova · 2024-06-05T12:44:15Z

Decide on the minimum React & TypeScript version

On React, we decided on React 17

Signed-off-by: Diego Andai <diego@mui.com>

DiegoAndai · 2024-06-05T21:09:40Z

@siriwatknp I updated the PR after some breaking changes were added to the migration guide in other PRs. I haven't forgotten about adding the components and componentsProps to the deprecation section 😅 I just haven't had time yet, but I'll get to it.

…igration-v6

danilo-leal

Looking great! Curious to see what Sam thinks of all these suggestions 😬
Also, are we not mentioning React 19 as a v6 highlight? 🤔 I think we should!

danilo-leal · 2024-06-11T15:21:34Z

docs/data/material/migration/migration-v5/migration-v5.md

The URL name confused me 😅 It makes me think that this is docs for migrating to v5 instead of from v5 to v6. Maybe we should change it to: migrating-to-v6?

Me too. I am not sure why all the previous migration pages use this pattern 🤔

Yeah I was confused as well when I created the files 😅: #41561 (comment). But I just followed the convention.

I think migrating-to-vX is a better convention, assuming we're always migrating from vN to vN+1.

danilo-leal · 2024-06-11T15:22:17Z

docs/data/material/migration/migration-v5/migration-v5.md

@@ -11,35 +11,78 @@ In the `package.json` file, change the package version from `latest` to `next`.
 +"@mui/material": "next",
 ```

+If you are one of these packages, be sure to change the version to `next` too:


Suggested change

If you are one of these packages, be sure to change the version to `next` too:

If you use one of these packages, change the version to `next` too:

I assume the original copy was saying "if you are using" 😅

danilo-leal · 2024-06-11T15:25:25Z

docs/data/material/migration/migration-v5/migration-v5.md

+Material UI v6 includes many bug fixes and improvements over v5.
+
+The biggest highlight in v6 is the opt-in support for Pigment CSS which enable styles extraction that get rid of style recalculation and reduce bundle size.


I'd glue these sentences here with something like:

Suggested change

Material UI v6 includes many bug fixes and improvements over v5.

The biggest highlight in v6 is the opt-in support for Pigment CSS which enable styles extraction that get rid of style recalculation and reduce bundle size.

Material UI v6's biggest highlight is the inclusion of Pigment CSS, a next-gen zero-runtime CSS-in-JS library, as an opt-in styling engine.

Using it will make your project compatible with React Server Components and reduce its bundle size due to the styles extraction, avoiding client-side recalculation.

danilo-leal · 2024-06-11T15:26:48Z

docs/data/material/migration/migration-v5/migration-v5.md

+
+The biggest highlight in v6 is the opt-in support for Pigment CSS which enable styles extraction that get rid of style recalculation and reduce bundle size.
+
+Apart from the support for Pigment CSS, the v6 release provides a stable API for adopting CSS variables which open more customization possibilities and offers a more enjoyable developer experience.


Suggested change

Apart from the support for Pigment CSS, the v6 release provides a stable API for adopting CSS variables which open more customization possibilities and offers a more enjoyable developer experience.

Aside from that, the CSS variables API for Material UI is now stable in v6.

Relying on CSS variables allows for more intricate customization possibilities and better overall DX.

danilo-leal · 2024-06-11T15:30:40Z

docs/data/material/migration/migration-v5/migration-v5.md

+
+Apart from the support for Pigment CSS, the v6 release provides a stable API for adopting CSS variables which open more customization possibilities and offers a more enjoyable developer experience.
+
+Additionally, the v6 release does not include major breaking changes, apart from the browser support & node.js version bump. Instead, they are deprecated to bring more consistent developer experience which can be migrated using our codemods.


Suggested change

Additionally, the v6 release does not include major breaking changes, apart from the browser support & node.js version bump. Instead, they are deprecated to bring more consistent developer experience which can be migrated using our codemods.

A major feedback we've learned from the v5 cycle is to reduce the number of breaking changes to the smallest.

Material UI v6 does exactly that: minimal breaking changes, including only browser support updates and a Node.js version bump.

These updates can, for the most part, be migrated automatically via codemods.

It feels important to highlight how this contrasts with v5 and be accountable to the community that we've learned the lesson here. Also added "for the most part" as I wasn't sure if the codemods could tackle everything, so feel free to drop it if that's the case.

danilo-leal · 2024-06-11T15:40:03Z

docs/data/material/migration/migration-v5/migration-v5.md

+
+### System props
+
+System props are deprecated in `Box`, `Typography`, `Link`, `Grid`, and `Stack` components.


Suggested change

System props are deprecated in `Box`, `Typography`, `Link`, `Grid`, and `Stack` components.

System props, such as `mt={*}`, `color={*}`, and others, are deprecated in the Box, Typography, Link, Grid, and Stack components.

Just to give quick examples here. It'd be even better if we linked to a place where I could see all previously existing system props. Also removing the backticks from the components.

danilo-leal · 2024-06-11T15:42:21Z

docs/data/material/migration/migration-v5/migration-v5.md

+
+### Theme component variants
+
+Theme component variants has been merged with the theme style overrides by targeting the `root` slot of the component:


Suggested change

Theme component variants has been merged with the theme style overrides by targeting the `root` slot of the component:

Custom component variants defined in the theme are now merged with the theme style overrides, defined within the `root` slot of the component:

Changing the tense here. Also, saying "custom component variants defined in theme" sounds clearer than "theme component variants", which I had to stop for a second to understand what it was.

danilo-leal · 2024-06-11T15:43:53Z

docs/data/material/migration/migration-v5/migration-v5.md

+ })
+```
+
+This reduces the API surface and let you define variants in other slots of the component.


Suggested change

This reduces the API surface and let you define variants in other slots of the component.

This reduces the API surface and lets you define variants in other slots of the component.

danilo-leal · 2024-06-11T15:44:30Z

docs/data/material/migration/migration-v5/migration-v5.md

+We try to align with types released by [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) (that is packages published on npm under the `@types` namespace).
+
+We will not change the minimum supported version in a minor version of Material UI.
+However, we generally recommend not to use a TypeScript version older than the lowest supported version of DefinitelyTyped.


Suggested change

However, we generally recommend not to use a TypeScript version older than the lowest supported version of DefinitelyTyped.

However, we recommend not using a TypeScript version older than the lowest supported version by DefinitelyTyped.

danilo-leal · 2024-06-11T15:45:08Z

docs/data/material/migration/migration-v5/migration-v5.md

 <!-- #stable-snapshot -->

+- Node 18 (up from 12)


Suggested change

- Node 18 (up from 12)

- Node.js 18 (up from 12)

DiegoAndai · 2024-06-12T12:56:55Z

are we not mentioning React 19 as a v6 highlight?

Not ready yet so I think we can add it when it is

DiegoAndai · 2024-06-12T13:03:29Z

@siriwatknp I added the section about components and componentsProps deprecations.

As discussed, the *Component, *Props, and composed classes deprecations will continue to be added after v6 release, so I'm not mentioning them here.

update migration v5

bd14173

siriwatknp added the docs Improvements or additions to the documentation label May 14, 2024

siriwatknp changed the title ~~[docs] Add migration for v6~~ [WIP][docs] Add migration for v6 May 14, 2024

siriwatknp added the on hold There is a blocker, we need to wait label May 14, 2024

siriwatknp commented May 14, 2024

View reviewed changes

docs/data/material/migration/migration-v5/migration-v5.md Outdated Show resolved Hide resolved

update docs

0dac3c4

siriwatknp commented May 14, 2024

View reviewed changes

docs/data/material/migration/migration-v5/migration-v5.md Show resolved Hide resolved

siriwatknp commented May 15, 2024

View reviewed changes

docs/data/material/migration/migration-v5/migration-v5.md Show resolved Hide resolved

siriwatknp added this to the Material UI: v6 milestone May 16, 2024

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label May 17, 2024

siriwatknp added 2 commits May 17, 2024 12:17

Merge branch 'next' of https://github.com/mui/material-ui into docs/m…

c1785bc

…igration-v6

move deprecating API under v6

8dbaa4a

DiegoAndai self-assigned this May 24, 2024

mnajdova reviewed May 27, 2024

View reviewed changes

docs/data/material/migration/migration-v5/migration-v5.md Outdated Show resolved Hide resolved

mnajdova reviewed May 27, 2024

View reviewed changes

docs/data/material/migration/migration-v5/migration-v5.md Outdated Show resolved Hide resolved

siriwatknp added 2 commits May 27, 2024 19:38

Merge branch 'next' of https://github.com/mui/material-ui into docs/m…

bb7b1a5

…igration-v6

update docs

4379480

github-actions bot added PR: out-of-date The pull request has merge conflicts and can't be merged and removed PR: out-of-date The pull request has merge conflicts and can't be merged labels May 28, 2024

Merge branch 'next' into docs/migration-v6

9991f8f

Signed-off-by: Diego Andai <diego@mui.com>

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Jun 5, 2024

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Jun 10, 2024

Merge branch 'next' of https://github.com/mui/material-ui into docs/m…

25e4232

…igration-v6

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Jun 11, 2024

siriwatknp changed the title ~~[WIP][docs] Add migration for v6~~ [docs] Add first batch of v6 migration Jun 11, 2024

siriwatknp requested a review from DiegoAndai June 11, 2024 06:38

siriwatknp requested review from danilo-leal and samuelsycamore June 11, 2024 06:38

siriwatknp marked this pull request as ready for review June 11, 2024 06:38

add suggestion

ab5f2e4

siriwatknp added v6.x migration and removed on hold There is a blocker, we need to wait labels Jun 11, 2024

danilo-leal reviewed Jun 11, 2024

View reviewed changes

danilo-leal added the package: material-ui Specific to @mui/material label Jun 11, 2024

danilo-leal changed the title ~~[docs] Add first batch of v6 migration~~ [material-ui][docs] Add first batch of v6 migration Jun 11, 2024

siriwatknp mentioned this pull request Jun 12, 2024

[material-ui][docs] Add some writing tweaks to v6 migration page #42623

Open

1 task

Add components props deprecation section

51c4c59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[material-ui][docs] Add first batch of v6 migration #42242

[material-ui][docs] Add first batch of v6 migration #42242

siriwatknp commented May 14, 2024 •

edited by danilo-leal

mui-bot commented May 14, 2024 •

edited

DiegoAndai commented May 17, 2024

mnajdova commented Jun 5, 2024

DiegoAndai commented Jun 5, 2024

danilo-leal left a comment

danilo-leal Jun 11, 2024

siriwatknp Jun 12, 2024 •

edited

DiegoAndai Jun 12, 2024

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024 •

edited

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024

danilo-leal Jun 11, 2024

DiegoAndai commented Jun 12, 2024

DiegoAndai commented Jun 12, 2024

	If you are one of these packages, be sure to change the version to `next` too:
	If you use one of these packages, change the version to `next` too:

		Material UI v6 includes many bug fixes and improvements over v5.

		The biggest highlight in v6 is the opt-in support for Pigment CSS which enable styles extraction that get rid of style recalculation and reduce bundle size.


		The biggest highlight in v6 is the opt-in support for Pigment CSS which enable styles extraction that get rid of style recalculation and reduce bundle size.

		Apart from the support for Pigment CSS, the v6 release provides a stable API for adopting CSS variables which open more customization possibilities and offers a more enjoyable developer experience.

	Apart from the support for Pigment CSS, the v6 release provides a stable API for adopting CSS variables which open more customization possibilities and offers a more enjoyable developer experience.
	Aside from that, the CSS variables API for Material UI is now stable in v6.
	Relying on CSS variables allows for more intricate customization possibilities and better overall DX.


		Apart from the support for Pigment CSS, the v6 release provides a stable API for adopting CSS variables which open more customization possibilities and offers a more enjoyable developer experience.

		Additionally, the v6 release does not include major breaking changes, apart from the browser support & node.js version bump. Instead, they are deprecated to bring more consistent developer experience which can be migrated using our codemods.

-Additionally, the v6 release does not include major breaking changes, apart from the browser support & node.js version bump. Instead, they are deprecated to bring more consistent developer experience which can be migrated using our codemods.
+A major feedback we've learned from the v5 cycle is to reduce the number of breaking changes to the smallest.
+Material UI v6 does exactly that: minimal breaking changes, including only browser support updates and a Node.js version bump.
+These updates can, for the most part, be migrated automatically via codemods.


		### System props

		System props are deprecated in `Box`, `Typography`, `Link`, `Grid`, and `Stack` components.

	System props are deprecated in `Box`, `Typography`, `Link`, `Grid`, and `Stack` components.
	System props, such as `mt={}`, `color={}`, and others, are deprecated in the Box, Typography, Link, Grid, and Stack components.


		### Theme component variants

		Theme component variants has been merged with the theme style overrides by targeting the `root` slot of the component:

	Theme component variants has been merged with the theme style overrides by targeting the `root` slot of the component:
	Custom component variants defined in the theme are now merged with the theme style overrides, defined within the `root` slot of the component:

	This reduces the API surface and let you define variants in other slots of the component.
	This reduces the API surface and lets you define variants in other slots of the component.

	However, we generally recommend not to use a TypeScript version older than the lowest supported version of DefinitelyTyped.
	However, we recommend not using a TypeScript version older than the lowest supported version by DefinitelyTyped.

[material-ui][docs] Add first batch of v6 migration #42242

Are you sure you want to change the base?

[material-ui][docs] Add first batch of v6 migration #42242

Conversation

siriwatknp commented May 14, 2024 • edited by danilo-leal

Out of scope

mui-bot commented May 14, 2024 • edited

Netlify deploy preview

Bundle size report

DiegoAndai commented May 17, 2024

mnajdova commented Jun 5, 2024

DiegoAndai commented Jun 5, 2024

danilo-leal left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

siriwatknp Jun 12, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danilo-leal Jun 11, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DiegoAndai commented Jun 12, 2024

DiegoAndai commented Jun 12, 2024

siriwatknp commented May 14, 2024 •

edited by danilo-leal

mui-bot commented May 14, 2024 •

edited

siriwatknp Jun 12, 2024 •

edited

danilo-leal Jun 11, 2024 •

edited