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.

Sign up for GitHub

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
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
2e776b7
Add deprecations migration guide
DiegoAndai Jan 23, 2024
cf4d74b
Address reviewdog review
DiegoAndai Jan 23, 2024
c736429
Improve copy and add placeholder links
DiegoAndai Jan 25, 2024
d1cce84
Add links and reduce duplication
DiegoAndai Jan 30, 2024
43fb3c6
Add link in deprecated Accordion props to guide
DiegoAndai Jan 30, 2024
4cc8786
Apply suggestions from code review
DiegoAndai Jan 31, 2024
a652ff4
Update file names and copy
DiegoAndai Jan 31, 2024
f8af7de
Replace regular space with non-breaking space
DiegoAndai Feb 5, 2024
46623cb
trigger ci
DiegoAndai Feb 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions ...rial/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Migrating from deprecated APIs

<p class="description">Learn how to migrate away from recently deprecated APIs before they become breaking changes.</p>

## Why you should migrate

Features become deprecated over time as maintainers make improvements to the APIs.
Migrating to these improved APIs results in a better developer experience, so it's in your best interest to stay up to date.
Deprecated APIs often become breaking changes in subsequent major versions, so the sooner you migrate, the smoother the next major update will be.

Check warning on line 9 in docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Google.Will] Avoid using 'will'.

Raw Output:
{"message": "[Google.Will] Avoid using 'will'.", "location": {"path": "docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md", "range": {"start": {"line": 9, "column": 139}}}, "severity": "WARNING"}

## Migrating

Material UI provides the `deprecations/all` codemod to help you stay up to date with minimal effort.

```bash
npx @mui/codemod@latest deprecations/all <path>
```

This command runs all the current [deprecations codemods](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#deprecations), automatically migrating to the updated API.
You can run this codemod as often as necessary to keep up with the latest changes.

:::info

If you need to manually migrate from a deprecated API, you can find examples below for all deprecations that have been added in Material UI v5.
If you need to run a specific codemod, those are also linked below.

:::

## Accordion

### 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 •
edited
Loading

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?


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

@oliviertassinari oliviertassinari Feb 6, 2024 •
edited
Loading

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 •
edited
Loading

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


```diff
<Accordion
- TransitionProps={{ unmountOnExit: true }}
+ slotProps={{ transition: { unmountOnExit: true } }}
/>
```
4 changes: 4 additions & 0 deletions docs/data/material/pages.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,10 @@ const pages: MuiPage[] = [
pathname: '/material-ui/migration',
title: 'Migration',
children: [
{
pathname: '/material-ui/migration/migrating-from-deprecated-apis',
title: 'Migrating from deprecated APIs',
},
{
pathname: '/material-ui/migration/migration-grid-v2',
title: 'Migrating to Grid v2',
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/material-ui/api/accordion.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@
"TransitionComponent": {
"type": { "name": "elementType" },
"deprecated": true,
"deprecationInfo": "Use <code>slots.transition</code> instead. This prop will be removed in v7."
"deprecationInfo": "Use <code>slots.transition</code> instead. This prop will be removed in v7. <a href=\"/material-ui/migration/migrating-from-deprecated-apis/\">How to migrate</a>."
},
"TransitionProps": {
"type": { "name": "object" },
"deprecated": true,
"deprecationInfo": "Use <code>slotProps.transition</code> instead. This prop will be removed in v7."
"deprecationInfo": "Use <code>slotProps.transition</code> instead. This prop will be removed in v7. <a href=\"/material-ui/migration/migrating-from-deprecated-apis/\">How to migrate</a>."
}
},
"name": "Accordion",
Expand Down
7 changes: 7 additions & 0 deletions docs/pages/material-ui/migration/migrating-from-deprecated-APIs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,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} />;
}
Comment on lines +1 to +7
Copy link
Member

@oliviertassinari oliviertassinari Feb 6, 2024 •
edited
Loading

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? :)

1 change: 1 addition & 0 deletions docs/translations/translations.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -473,6 +473,7 @@
"/material-ui/discover-more/vision": "Vision",
"/material-ui/discover-more/changelog": "Changelog",
"/material-ui/migration": "Migration",
"/material-ui/migration/migrating-from-deprecated-apis": "Migrating from deprecated APIs",
"/material-ui/migration/migration-grid-v2": "Migrating to Grid v2",
"Upgrade to v5": "Upgrade to v5",
"/material-ui/migration/migration-v4": "Migrating to v5: getting started",
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-material/src/Accordion/Accordion.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,15 +79,15 @@ export type AccordionTypeMap<
/**
* The component used for the transition.
* [Follow this guide](/material-ui/transitions/#transitioncomponent-prop) to learn more about the requirements for this component.
* @deprecated Use `slots.transition` instead. This prop will be removed in v7.
* @deprecated Use `slots.transition` instead. This prop will be removed in v7. [How to migrate](/material-ui/migration/migrating-from-deprecated-apis/).
*/
TransitionComponent?: React.JSXElementConstructor<
TransitionProps & { children?: React.ReactElement<any, any> }
>;
/**
* Props applied to the transition element.
* By default, the element is based on this [`Transition`](http://reactcommunity.org/react-transition-group/transition/) component.
* @deprecated Use `slotProps.transition` instead. This prop will be removed in v7.
* @deprecated Use `slotProps.transition` instead. This prop will be removed in v7. [How to migrate](/material-ui/migration/migrating-from-deprecated-apis/).
*/
TransitionProps?: TransitionProps;
} & AccordionSlotsAndSlotProps;
Expand Down
4 changes: 2 additions & 2 deletions packages/mui-material/src/Accordion/Accordion.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,13 +293,13 @@ Accordion.propTypes /* remove-proptypes */ = {
/**
* The component used for the transition.
* [Follow this guide](/material-ui/transitions/#transitioncomponent-prop) to learn more about the requirements for this component.
* @deprecated Use `slots.transition` instead. This prop will be removed in v7.
* @deprecated Use `slots.transition` instead. This prop will be removed in v7. [How to migrate](/material-ui/migration/migrating-from-deprecated-apis/).
*/
TransitionComponent: PropTypes.elementType,
/**
* Props applied to the transition element.
* By default, the element is based on this [`Transition`](http://reactcommunity.org/react-transition-group/transition/) component.
* @deprecated Use `slotProps.transition` instead. This prop will be removed in v7.
* @deprecated Use `slotProps.transition` instead. This prop will be removed in v7. [How to migrate](/material-ui/migration/migrating-from-deprecated-apis/).
*/
TransitionProps: PropTypes.object,
};
Expand Down
Loading