Add migration guide for Material 3 #10076

TahaTesser · 2024-01-23T11:11:27Z

Fixes Create a migration guide for Material 3

TahaTesser · 2024-01-23T11:14:33Z

src/resources/migrating-to-material-3.md

+`useMaterial3` to `false`. However, this is just a temporary solution. The
+`useMaterial3` flag _and_ the Material 2 implementation will eventually be
+removed as part of Flutter’s deprecation policy.


@HansMuller
This was written before your comment. Is this still accurate?

If you have any suggestions on updating this.

Not Hans, but my understanding is that this is still true.

It is still true. Before we deprecate M2 we'll provide a theme, in a separate public package, that closely approximates the M2 defaults.

flutter-website-bot · 2024-01-23T11:20:40Z

Visit the preview URL for this PR (updated for commit f206ad2):

https://flutter-docs-prod--pr10076-m3-migration-guide-m69kcbls.web.app

TahaTesser · 2024-01-23T11:44:33Z

@parlough
I just used the resources folder as a placeholder. Do you've any ideas on where to place this guide on the website? Not sure if this belongs to breaking-changes folder.

parlough · 2024-01-23T16:34:39Z

Thanks so much for working on this @TahaTesser! This will be an extremely useful reference for developers completing the migration. I'm excited to read it too :D

Do you've any ideas on where to place this guide on the website? Not sure if this belongs to breaking-changes folder.

Good question! Despite the name, breaking-changes is probably the best place for this. It's for any sort of migration guide or change that users should know about, but isn't super necessary after they've completed that migration.

However, we can link to it from elsewhere as well to increase discoverability. I'd likely link to it from the Material Design for Flutter page where it discusses the transition, the Flutter 3.16 section of Breaking changes and migration guides, perhaps in the sidenav directly under "Material design", and wherever else you think would be helpful. Shams might have some opinions as well :)

I'd also consider adding a short redirect link in the firebase.json file so it's easier to share outside the site, maybe something simple like /material-3-migration?

sfshaza2 · 2024-01-23T18:06:27Z

Yes, I want this added to breaking changes and linked to from the Material page. I've already reviewed it as a Google Doc, but will review it as a PR, too. :D

sfshaza2

This is a great PR, @TahaTesser! I do have some fairly minor grammatical edits. Also:

Move this new file to https://docs.flutter.dev/release/breaking-changes
Add this guide to the index file in that directory under the "3.16 release".
Add a prominent link to this file from the https://docs.flutter.dev/ui/widgets/material
Add a shortcut to the firebase.json file (as suggested by Parker)
Add it to the sidenav (src/data/sidenav.yml) so that it appears under Material (as suggested by Parker)

src/resources/migrating-to-material-3.md

sfshaza2 · 2024-01-23T18:25:38Z

src/resources/migrating-to-material-3.md

+`useMaterial3` to `false`. However, this is just a temporary solution. The
+`useMaterial3` flag _and_ the Material 2 implementation will eventually be
+removed as part of Flutter’s deprecation policy.


Not Hans, but my understanding is that this is still true.

src/resources/migrating-to-material-3.md

TahaTesser · 2024-01-24T13:40:29Z

@parlough
Address the feedback. For some reason there is a build failure for check links and staging actions

sfshaza2 · 2024-01-24T17:56:43Z

/gcbrun

sfshaza2 · 2024-01-24T17:57:26Z

I'm trying the build again, as the log error is weird

parlough

Thanks @TahaTesser! A few comments with the fix for the build failure and some suggestions to consider:

firebase.json

src/_data/sidenav.yml

src/release/breaking-changes/material-3-migration.md

src/release/breaking-changes/index.md

TahaTesser · 2024-01-25T18:13:39Z

Thanks @TahaTesser! A few comments with the fix for the build failure and some suggestions to consider:

Thanks for the suggestions!

parlough

Thanks for making those adjustments @TahaTesser!

I just did a quick scan as it sounds like others reviewed the content, but looks good to me overall. Do wait for a final approval from @sfshaza2 though :)

src/_data/catalog/index.json

src/release/breaking-changes/material-3-migration.md

domesticmouse

Please wait for @sfshaza2's LGTM

domesticmouse · 2024-01-29T01:33:44Z

src/release/breaking-changes/material-3-migration.md

+setting the `useMaterial3` flag to true. As of the Flutter 3.16 release
+(November 2023), `useMaterial3` is true by default.
+
+By the way, you _can_ recapture Material 2 behavior in your app by setting the


Nit: suggest "revert to Material 2" to make this more easily understood by ESL developers.

domesticmouse · 2024-01-29T01:59:18Z

src/release/breaking-changes/material-3-migration.md

+`ColorScheme.surfaceTint` indicates an elevated widget.
+Some widgets use different colors.
+
+To return your app’s UI to its previous behavior (which we don't particularly


Drop the 'particularly' as overly complex.

domesticmouse · 2024-01-29T02:00:20Z

src/release/breaking-changes/material-3-migration.md

+indicate elevation (for example, `Card` and `ElevatedButton`) and others might
+only use `surfaceTint` to indicate elevation (such as `AppBar`).
+
+If you must return to a widget’s previous behavior, set, set `Colors.transparent`


Suggest: 'To return to the widget's previous behavior'

The reason I said "must" is that this page spends a lot of time telling folks how to return to previous behavior, but we really don't want to encourage that.

sfshaza2

lgtm! Thanks for this herculean effort, @TahaTesser!

TahaTesser · 2024-01-29T22:23:49Z

lgtm! Thanks for this herculean effort, @TahaTesser!

Wouldn't have been possible without you @sfshaza2 & @parlough 💙

Fixes [Create a migration guide for Material 3](flutter/flutter#119319)

TahaTesser requested review from sfshaza2, atsansone, parlough, domesticmouse and MaryaBelanger as code owners January 23, 2024 11:11

TahaTesser commented Jan 23, 2024

View reviewed changes

TahaTesser force-pushed the m3-migration-guide branch from bb4a407 to 8e0062d Compare January 23, 2024 11:36

parlough requested a review from HansMuller January 23, 2024 16:34

parlough added review.copy Awaiting Copy Review review.tech Awaiting Technical Review labels Jan 23, 2024

parlough assigned HansMuller and sfshaza2 Jan 23, 2024

sfshaza2 requested changes Jan 23, 2024

View reviewed changes

atsansone added review.await-update Awaiting Updates after Edits and removed review.copy Awaiting Copy Review review.tech Awaiting Technical Review labels Jan 23, 2024

TahaTesser requested a review from khanhnwin as a code owner January 24, 2024 11:31

TahaTesser force-pushed the m3-migration-guide branch 2 times, most recently from f17ad08 to d8588f0 Compare January 24, 2024 13:09

TahaTesser added 2 commits January 24, 2024 15:23

Add migration guide for Material 3

4a4b09f

Address feedback

66f9e56

TahaTesser force-pushed the m3-migration-guide branch from d8588f0 to 66f9e56 Compare January 24, 2024 13:23

TahaTesser requested a review from sfshaza2 January 24, 2024 13:28

parlough reviewed Jan 24, 2024

View reviewed changes

Address feedback

89c39db

TahaTesser requested a review from parlough January 24, 2024 21:30

parlough approved these changes Jan 25, 2024

View reviewed changes

parlough unassigned HansMuller Jan 25, 2024

parlough added the review.copy Awaiting Copy Review label Jan 25, 2024

Address feedback

ffe882a

domesticmouse approved these changes Jan 29, 2024

View reviewed changes

Address feedback

f206ad2

sfshaza2 approved these changes Jan 29, 2024

View reviewed changes

sfshaza2 merged commit cbcf815 into flutter:main Jan 29, 2024
9 checks passed

TahaTesser deleted the m3-migration-guide branch January 29, 2024 21:40

atsansone pushed a commit to atsansone/website that referenced this pull request Feb 15, 2024

Add migration guide for Material 3 (flutter#10076)

b58e488

Fixes [Create a migration guide for Material 3](flutter/flutter#119319)

atsansone pushed a commit to atsansone/website that referenced this pull request Apr 5, 2024

Add migration guide for Material 3 (flutter#10076)

70bba54

Fixes [Create a migration guide for Material 3](flutter/flutter#119319)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add migration guide for Material 3 #10076

Add migration guide for Material 3 #10076

TahaTesser commented Jan 23, 2024 •

edited by parlough

TahaTesser Jan 23, 2024

sfshaza2 Jan 23, 2024

HansMuller Jan 26, 2024

flutter-website-bot commented Jan 23, 2024 •

edited

TahaTesser commented Jan 23, 2024 •

edited

parlough commented Jan 23, 2024 •

edited

sfshaza2 commented Jan 23, 2024

sfshaza2 left a comment

sfshaza2 Jan 23, 2024

TahaTesser commented Jan 24, 2024

sfshaza2 commented Jan 24, 2024 •

edited by parlough

sfshaza2 commented Jan 24, 2024

parlough left a comment

TahaTesser commented Jan 25, 2024

parlough left a comment

domesticmouse left a comment

domesticmouse Jan 29, 2024

domesticmouse Jan 29, 2024

domesticmouse Jan 29, 2024

sfshaza2 Jan 29, 2024

sfshaza2 left a comment

TahaTesser commented Jan 29, 2024

Add migration guide for Material 3 #10076

Add migration guide for Material 3 #10076

Conversation

TahaTesser commented Jan 23, 2024 • edited by parlough

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flutter-website-bot commented Jan 23, 2024 • edited

TahaTesser commented Jan 23, 2024 • edited

parlough commented Jan 23, 2024 • edited

sfshaza2 commented Jan 23, 2024

sfshaza2 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TahaTesser commented Jan 24, 2024

sfshaza2 commented Jan 24, 2024 • edited by parlough

sfshaza2 commented Jan 24, 2024

parlough left a comment

Choose a reason for hiding this comment

TahaTesser commented Jan 25, 2024

parlough left a comment

Choose a reason for hiding this comment

domesticmouse left a 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

sfshaza2 left a comment

Choose a reason for hiding this comment

TahaTesser commented Jan 29, 2024

TahaTesser commented Jan 23, 2024 •

edited by parlough

flutter-website-bot commented Jan 23, 2024 •

edited

TahaTesser commented Jan 23, 2024 •

edited

parlough commented Jan 23, 2024 •

edited

sfshaza2 commented Jan 24, 2024 •

edited by parlough