From ddb256e2741f34b2d10bdaaf2b81736d3de2ce6a Mon Sep 17 00:00:00 2001
From: Jeppe Reinhold <jeppe@reinhold.is>
Date: Wed, 11 Jan 2023 00:17:13 +0100
Subject: [PATCH] migration notes and links

---
 MIGRATION.md                              | 13 ++++++++++---
 code/ui/blocks/src/blocks/Description.tsx | 17 ++++++++++-------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/MIGRATION.md b/MIGRATION.md
index 74a25caa45a..f1f21551870 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -41,6 +41,7 @@
   - [Docs Changes](#docs-changes)
     - [Standalone docs files](#standalone-docs-files)
     - [Referencing stories in docs files](#referencing-stories-in-docs-files)
+    - [Description block, `parameters.notes` and `parameters.info`](#description-block-parametersnotes-and-parametersinfo)
     - [Autodocs](#autodocs)
     - [Configuring the Docs Container](#configuring-the-docs-container)
     - [External Docs](#external-docs)
@@ -306,8 +307,8 @@ To opt-out of the old behavior you can set the `storyStoreV7` feature flag to `f
 module.exports = {
   features: {
     storyStoreV7: false,
-  }
-}
+  },
+};
 ```
 
 #### Removed global client APIs
@@ -796,6 +797,13 @@ import * as SecondComponentStories from './second-component.stories';
 <Story of={SecondComponentStories.standard} meta={SecondComponentStories} />
 ```
 
+#### Description block, `parameters.notes` and `parameters.info`
+
+In 6.5 the Description doc block accepted a range of different props, `markdown`, `type` and `children` as a way to customize the content.
+The props have been simplified and the block now only accepts an `of` prop, which can be a reference to either a CSF file, a default export (meta) or a story export, depending on which description you want to be shown. See TDB DOCS LINK for a deeper explanation of the new prop.
+
+`parameters.notes` and `parameters.info` have been deprecated as a way to specify descriptions. Instead use JSDoc comments above the default export or story export, or use `parameters.docs.description.story | component` directly. See TDB DOCS LINK for a deeper explanation on how to write descriptions.
+
 #### Autodocs
 
 In 7.0, rather than rendering each story in "docs view mode", Autodocs (formerly known as "Docs Page") operates by adding additional sidebar entries for each component. By default it uses the same template as was used in 6.x, and the entries are entitled `Docs`.
@@ -3812,4 +3820,3 @@ If you **are** using these addons, it takes two steps to migrate:
   ```
 
   <!-- markdown-link-check-enable -->
-
diff --git a/code/ui/blocks/src/blocks/Description.tsx b/code/ui/blocks/src/blocks/Description.tsx
index ef512fd82e7..6ce7de0ed31 100644
--- a/code/ui/blocks/src/blocks/Description.tsx
+++ b/code/ui/blocks/src/blocks/Description.tsx
@@ -20,6 +20,9 @@ export enum DescriptionType {
 type Notes = string | any;
 type Info = string | any;
 
+const DEPRECATION_MIGRATION_LINK =
+  'https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo';
+
 interface DescriptionProps {
   /**
    * Specify where to get the description from. Can be a component, a CSF file or a story.
@@ -27,15 +30,15 @@ interface DescriptionProps {
    */
   of?: Of;
   /**
-   * @deprecated Manually specifying description type is deprecated. In the future all descriptions will be extracted from JSDocs on the meta, story or component.
+   * @deprecated Manually specifying description type is deprecated. See https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo
    */
   type?: DescriptionType;
   /**
-   * @deprecated The 'markdown' prop on the Description block is deprecated. Write the markdown directly in the .mdx file instead
+   * @deprecated The 'markdown' prop on the Description block is deprecated. See https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo
    */
   markdown?: string;
   /**
-   * @deprecated The 'children' prop on the Description block is deprecated. Write the markdown directly in the .mdx file instead
+   * @deprecated The 'children' prop on the Description block is deprecated. See https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#description-block-parametersnotes-and-parametersinfo
    */
   children?: string;
 }
@@ -96,7 +99,7 @@ const getDescriptionFromDeprecatedProps = (
   const { notes, info, docs } = parameters;
   if (Boolean(notes) || Boolean(info)) {
     deprecate(
-      "Using 'parameters.notes' or 'parameters.info' properties to describe stories is deprecated. Write JSDocs directly at the meta, story or component instead."
+      `Using 'parameters.notes' or 'parameters.info' properties to describe stories is deprecated. See ${DEPRECATION_MIGRATION_LINK}`
     );
   }
 
@@ -134,17 +137,17 @@ const DescriptionContainer: FC<DescriptionProps> = (props) => {
   }
   if (type) {
     deprecate(
-      'Manually specifying description type is deprecated. In 7.0 all descriptions will be extracted from JSDocs on the meta, story or component.'
+      `Manually specifying description type is deprecated. See ${DEPRECATION_MIGRATION_LINK}`
     );
   }
   if (markdownProp) {
     deprecate(
-      "The 'markdown' prop on the Description block is deprecated. Write the markdown directly in the .mdx file instead"
+      `The 'markdown' prop on the Description block is deprecated. See ${DEPRECATION_MIGRATION_LINK}`
     );
   }
   if (children) {
     deprecate(
-      "The 'children' prop on the Description block is deprecated. Write the markdown directly in the .mdx file instead."
+      `The 'children' prop on the Description block is deprecated. See ${DEPRECATION_MIGRATION_LINK}`
     );
   }
   return markdown ? <Description markdown={markdown} /> : null;