Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[material-ui][docs] Add deprecations migration guide #40767

Merged
merged 9 commits into from
Feb 6, 2024

Conversation

DiegoAndai
Copy link
Member

@DiegoAndai DiegoAndai commented Jan 23, 2024

Part of: #40417

This PR adds the migration guide for current deprecations.

The idea is for this to be a "living" document:

  • Whenever we add a deprecation, an example is added to this migration guide as well to provide clarity
  • When a deprecation turns into a breaking change in a major version release, the example is moved to that version's migration guide

Preview: https://deploy-preview-40767--material-ui.netlify.app/material-ui/migration/migrating-from-deprecated-apis

@DiegoAndai DiegoAndai added docs Improvements or additions to the documentation package: material-ui Specific to @mui/material labels Jan 23, 2024
@DiegoAndai DiegoAndai self-assigned this Jan 23, 2024
@mui-bot
Copy link

mui-bot commented Jan 23, 2024

Copy link
Contributor

@samuelsycamore samuelsycamore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should add a callout in the Accordion demo doc as well? If you're using the deprecated APIs and you land on that page, you'll be confused when you can't find any mention of them in the Transition section.

DiegoAndai and others added 2 commits January 31, 2024 14:20
@DiegoAndai
Copy link
Member Author

DiegoAndai commented Jan 31, 2024

Hey @samuelsycamore, thanks for the review! I appreciate it 😊

The only ones I didn't apply:

  • I think the codemod link is necessary because:
    • I expect this doc to grow fast. Take a look at this list 😅: [material-ui] Standardize slots pattern and composed classes #40417
    • Users might want to run the specific codemod. We could have the command on the docs, duplicating the deprecations' README. It's better to link to it. The content is indeed similar but slightly different:
      • The doc is organized per deprecation to show atomic examples
      • The source is organized per codemod; there will probably be a relation of 1:N from codemod to deprecations
  • I would add another warning to the transitions demo. If users are using the deprecated props, they can find information on the API page. I want to avoid deprecation warnings on the demos; those are better suited to the API page. If we start getting issues about it, we can reconsider.

Question: How do I fix the "Use a non-breaking space for brand name ('Material UI' instead of 'Material UI')" review dog issue?

@danilo-leal
Copy link
Contributor

Question: How do I fix the "Use a non-breaking space for brand name ('Material UI' instead of 'Material UI')" review dog issue?

Through trial & error on #40403, I've found that using, e.g., Material UI, seems to make Vale happy for that. :)

@samuelsycamore
Copy link
Contributor

samuelsycamore commented Feb 1, 2024

@danilo-leal @DiegoAndai I could be wrong, but I believe it also works if you type a non-breaking space " " using shift + option + space (if you're on a Mac), which seems to be how the Vale rule is written, and makes it a little less ugly in the Markdown doc. cc @oliviertassinari who added this rule recently to confirm.

@danilo-leal
Copy link
Contributor

Ah, cool — didn't know about this shortcut; appreciate it! Might be worth adding it to the style guide :)

@samuelsycamore
Copy link
Contributor

Yes good idea! I imagine this is going to trip people up for awhile.

Copy link
Contributor

@samuelsycamore samuelsycamore left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tentatively approving before those pesky non-breaking spaces are added 😁

@DiegoAndai DiegoAndai force-pushed the deprecations-migration-guide branch 3 times, most recently from 196c2d5 to 5f99aa8 Compare February 5, 2024 21:12
@DiegoAndai DiegoAndai force-pushed the deprecations-migration-guide branch from 5f99aa8 to 46623cb Compare February 6, 2024 12:28
@DiegoAndai DiegoAndai merged commit b3298b8 into mui:master Feb 6, 2024
21 checks passed
@DiegoAndai DiegoAndai deleted the deprecations-migration-guide branch February 6, 2024 12:42
Copy link
Member

@oliviertassinari oliviertassinari left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: How do I fix the "Use a non-breaking space for brand name ('Material UI' instead of 'Material UI')" review dog issue?

cc @oliviertassinari who added this rule recently to confirm.

I use option⌥ + space to generate a nonbreaking space. We were using Material-UI in the past to solve this problem, but we changed the name in https://mui.com/blog/material-ui-is-now-mui/. This error comes from #40525. Material UI is a great option in JSX. For markdown, I'm not a fan, harder to read.

Comment on lines +37 to +38
- TransitionComponent={CustomTransition}
+ slots={{ transition: CustomTransition }}
Copy link
Member

@oliviertassinari oliviertassinari Feb 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should follow the git diff format with our syntax connections (two space tab):

Suggested change
- TransitionComponent={CustomTransition}
+ slots={{ transition: CustomTransition }}
- TransitionComponent={CustomTransition}
+ slots={{ transition: CustomTransition }}

x the other cases


### TransitionProps

The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):
Copy link
Member

@oliviertassinari oliviertassinari Feb 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should link to the default branch here so it continue to work even when we are on v6 next branch

Suggested change
The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):
The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/HEAD/packages/mui-codemod#accordion-props)):

x the other cases

Comment on lines +1 to +7
import * as React from 'react';
import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
import * as pageProps from 'docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md?@mui/markdown';

export default function Page() {
return <MarkdownDocs {...pageProps} />;
}
Copy link
Member

@oliviertassinari oliviertassinari Feb 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file pathname casing is wrong

Actual: docs/pages/material-ui/migration/migrating-from-deprecated-APIs.js
Expected: docs/pages/material-ui/migration/migrating-from-deprecated-apis.js

it leads to two bugs:

  1. Side nav not expanded (why I looked in the first place, seemed strange):
  1. Console errors:

Can we fix it? :)

Copy link
Member

@oliviertassinari oliviertassinari left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great to have this page 👍


### TransitionComponent

The Accordion's `TransitionComponent` was deprecated in favor of `slots.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):
Copy link
Member

@oliviertassinari oliviertassinari Feb 6, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that we should explain why we are making each deprecation. The very first thing as I developer I would want to understand is why am I going through this pain, what do I get? For example, https://mui.com/material-ui/migration/migration-v3/ illustrates this, we tried to justify why each breaking change.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! We have two overarching deprecation initiatives: standardizing the slots pattern and removing composed classes. I considered adding an explanation of those and then linking accordingly in each deprecation. Would that make sense?

@DiegoAndai
Copy link
Member Author

Thanks for the catches @oliviertassinari! handled in #40981

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation package: material-ui Specific to @mui/material
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants