Add deprecation warning & migration guide

MIGRATION.md

@@ -1,5 +1,8 @@
 <h1>Migration</h1>
 
+- [From version 6.2.x to 6.3.0](#from-version-62x-to-630)
+  - [6.3 deprecations](#63-deprecations)
+    - [Deprecated scoped blocks imports](#deprecated-scoped-blocks-imports)
 - [From version 6.1.x to 6.2.0](#from-version-61x-to-620)
   - [MDX pattern tweaked](#mdx-pattern-tweaked)
   - [6.2 Angular overhaul](#62-angular-overhaul)
@@ -152,6 +155,24 @@
   - [Packages renaming](#packages-renaming)
   - [Deprecated embedded addons](#deprecated-embedded-addons)
 
+## From version 6.2.x to 6.3.0
+
+### 6.3 deprecations
+
+#### Deprecated scoped blocks imports
+
+In 6.3, we changed doc block imports from `@storybook/addon-docs/blocks` to `@storybook/addon-docs`. This makes it possible for bundlers to automatically choose the ESM or CJS version of the library depending on the context.
+
+To update your code, you should be able to global replace `@storybook/addon-docs/blocks` with `@storybook/addon-docs`. Example:
+
+```js
+// before
+import { Meta, Story } from '@storybook/addon-docs/blocks';
+
+// after
+import { Meta, Story } from '@storybook/addon-docs';
+```
+
 ## From version 6.1.x to 6.2.0
 
 ### MDX pattern tweaked
@@ -209,7 +230,7 @@ Many Storybook packages are now available as ESModules in addition to CommonJS.
 
 ```js
 // In your jest config
-transformIgnorePatterns: ['/node_modules/(?!@storybook)']
+transformIgnorePatterns: ['/node_modules/(?!@storybook)'];
 ```
 
 ### 6.2 Deprecations

addons/docs/blocks.js

@@ -1 +1,14 @@
+import deprecate from 'util-deprecate';
+import dedent from 'ts-dedent';
+
+const warnBlocksImport = deprecate(
+  () => {},
+  dedent`
+    Importing from '@storybook/addon-docs/blocks' is deprecated, import directly from '@storybook/addon-docs' instead:
+    
+    https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-scoped-blocks-imports
+`
+);
+warnBlocksImport();
+
 export * from './dist/esm/blocks';

examples/cra-ts-essentials/src/stories/Test.stories.mdx

@@ -1,4 +1,6 @@
-<Meta title="DocsOnlyMdx" parameters={{ chromatic: { disable: true }} />
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="DocsOnlyMdx" parameters={{ chromatic: { disable: true } }} />
 
 # CRA TS Essentials