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

Author: DiegoAndai

docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

@@ -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.
+
+## 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)):
+
+```diff
+ <Accordion
+-    TransitionComponent={CustomTransition}
++    slots={{ transition: CustomTransition }}
+ />
+```
+
+### 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)):
+
+```diff
+ <Accordion
+-    TransitionProps={{ unmountOnExit: true }}
++    slotProps={{ transition: { unmountOnExit: true } }}
+ />
+```

docs/data/material/pages.ts

@@ -266,6 +266,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',

docs/pages/material-ui/api/accordion.json

@@ -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",

docs/pages/material-ui/migration/migrating-from-deprecated-APIs.js

@@ -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} />;
+}

docs/translations/translations.json

@@ -469,6 +469,7 @@
     "/material-ui/experimental-api/css-theme-variables/customization": "Customization",
     "/material-ui/experimental-api/css-theme-variables/migration": "Migrating to CSS variables",
     "/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",
     "/material-ui/migration/pickers-migration": "Migration from @material-ui/pickers",
     "Upgrade to v5": "Upgrade to v5",

packages/mui-material/src/Accordion/Accordion.d.ts

@@ -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;

packages/mui-material/src/Accordion/Accordion.js

@@ -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,
 };