[docs] Add typography v2 migration guide

docs/src/pages/style/typography/typography.md

@@ -54,3 +54,68 @@ In some situations you might not be able to use the `Typography` component.
 Hopefully, you might be able to take advantage of the [`typography`](/customization/default-theme?expend-path=$.typography) keys of the theme.
 
 {{"demo": "pages/style/typography/TypographyTheme.js"}}
+
+## Migration to typography v2
+
+The material design specification changed concerning variant names and styles. To allow
+a smooth transition we kept old variants and restyled variants for backwards compatibility
+but will log deprecation warnings. We will remove the old variants with our next
+major release.
+
+### Strategies
+
+To make an immediate switch to typography v2 you can simply pass `useNextVariants: true` when
+calling `createMuiTheme`:
+```js
+const theme = createMuiTheme({
+  typography: {
+    useNextVariants: true
+  }
+})
+```
+
+This will use new variants instead of old variants according to the following mapping:
+```json
+display4 => headline1
+display3 => headline2
+display2 => headline3
+display1 => headline4
+headline => headline5
+title => headline6
+subheading => subtitle1
+```
+Please note that this will still log deprecation warnings if you use one of the variants.
+We recommend you replace those old variants with the recommended variants to be prepared 
+for the next major release.
+
+See [Themes](/customization/themes/) for more information about how to use a global theme.
+
+You can also pass a `useNextVariant` to the `Typography` component to get the exact behavior as 
+described above but only for that particular instance.
+
+### Deprecation warnings
+Deprecation warnings are logged when:
+- `NODE_ENV` is not strictly equal to `production`
+- Regardless of whether you directly use the `Typography` component with a deprecated variant or another component
+  has a `Typography` component with a deprecated variant
+- You override the style of a deprecated variant with `createMuiTheme`
+- You override the style of a restyled variant without `useNextVariants` with `createMuiTheme`
+- Variants are considered deprecated if:
+    - They will be removed in the next major release. This includes:
+        - display4
+        - display3
+        - display2
+        - display1
+        - headline
+        - title
+        - subheading
+    - They will be restyled and `useNextVariants` is falsy. This includes:
+       - body2
+       - body1
+       - caption
+       - button
+
+In some cases the deprecation warnings can break your test suite which might be inconvenient.
+In those cases you can set the environment variable `MUI_SUPPRESS_DEPRECATION_WARNINGS` to
+a truthy value. Passing `ignoreDeprecationWarnings: true` to the typography options in
+`createMuiTheme` is equivalent.

packages/material-ui/src/styles/createTypography.js

@@ -1,6 +1,11 @@
 import deepmerge from 'deepmerge'; // < 1kb payload overhead when lodash/merge is > 3kb.
 import warning from 'warning';
-import { deprecatedVariants, nextVariantMapping, restyledVariants } from './typographyMigration';
+import {
+  deprecatedVariants,
+  migrationGuideMessage,
+  nextVariantMapping,
+  restyledVariants,
+} from './typographyMigration';
 
 function round(value) {
   return Math.round(value * 1e5) / 1e5;
@@ -38,16 +43,15 @@ export default function createTypography(palette, typography) {
 
   warning(
     !Object.keys(other).some(variant => deprecatedVariants.includes(variant)),
-    'Deprecation Warning: Material-UI: Your are passing a deprecated variant to createTypography.' +
-      ' Please read the migration guide.',
+    'Deprecation Warning: Material-UI: Your are passing a deprecated variant to ' +
+      `createTypography. ${migrationGuideMessage}`,
   );
 
   warning(
     useNextVariants || !Object.keys(other).some(variant => restyledVariants.includes(variant)),
     'Deprecation Warning: Material-UI: Your are passing a variant to createTypography ' +
-      'that will be restyled in the next major release ' +
-      'without indicating that you are using typography v2 (set `useNextVariants` to true. ' +
-      'Please read the migration guide.',
+      'that will be restyled in the next major release without indicating that you ' +
+      `are using typography v2 (set \`useNextVariants\` to true. ${migrationGuideMessage}`,
   );
 
   const coef = fontSize / 14;
@@ -64,8 +68,7 @@ export default function createTypography(palette, typography) {
     warning(
       ignoreDeprecationWarnings || !deprecatedVariants.includes(variant),
       'Deprecation Warning: Material-UI: You are using the deprecated typography variant ' +
-        `${variant} that will be removed in the next major release. ` +
-        'Check the migration guide.',
+        `${variant} that will be removed in the next major release. ${migrationGuideMessage}`,
     );
 
     const nextVariant = nextVariantMapping(variant);
@@ -88,8 +91,7 @@ export default function createTypography(palette, typography) {
     warning(
       ignoreDeprecationWarnings || !isRestyledVariant,
       'Deprecation Warning: Material-UI: You are using the typography variant ' +
-        `${variant} which will be restyled in the next major release.` +
-        'Check the migration guide',
+        `${variant} which will be restyled in the next major release. ${migrationGuideMessage}`,
     );
 
     return variant;

packages/material-ui/src/styles/typographyMigration.js

@@ -40,3 +40,6 @@ export function nextVariantMapping(variant) {
   }
   return nextVariant;
 }
+
+export const migrationGuideMessage =
+  '\nPlease read the migration guide under https://material-ui.com/style/typography#migration-to-typography-v2';