docs(react-persona): Adding migration guide (#25022)

change/@fluentui-react-persona-7470d036-2f82-454b-86fc-bd8282e46c2f.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "docs: Add migration guide.",
+  "packageName": "@fluentui/react-persona",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-persona/MIGRATION.md

@@ -0,0 +1,42 @@
+# Badge Migration
+
+## Migration from v8
+
+v8 offers a component equivalent to v9's `Persona`. However, the API is slightly different. The main difference is that v9's `Persona` does not handle the functionality of the `presence` and `avatar`. Instead, the `presence` and `avatar` are separate components that can be used in conjunction with `Persona`.
+
+Here's how the API of v8's `Persona` compares to the one from v9's `Persona` component:
+
+- `className` => `className`
+- `coinProps` => Use `avatar`'s or `presence`'s slot props
+- `componentRef` => NOT SUPPORTED - use `ref` instead
+- `hidePersonaDetails` => Use the `Avatar` component for this case
+- ```
+- `imageShouldFadeIn` => NOT SUPPORTED
+- `isOutOfOffice` => Use the `outOfOffice` prop of the `presence` slot. E.g.: `presence={{ outOfOffice: true }}`
+- `presence` => Use the `status` prop of the `presence` slot. E.g.: `presence={{ status: 'away' }}`
+- `presenceTitle` => NOT SUPPORTED
+- `showOverflowTooltip` => NOT SUPPORTED
+- `showUnknownPersonaCoin` => NOT SUPPORTED
+- `styles` => Use style customization through `className` instead
+
+## Property Mapping
+
+| v8 `Persona`             | v9 `Persona`                           |
+| ------------------------ | -------------------------------------- |
+| `coinProps`              | `avatar` or `badge` slot props         |
+| `coinSize`               | `size` in the `badge` or `avatar` slot |
+| `className`              | `className`                            |
+| `componentRef`           | `ref`                                  |
+| `hidePersonaDetails`     | -                                      |
+| `imageShouldFadeIn`      | -                                      |
+| `isOutOfOffice`          | `status` in `presence` slot props      |
+| `optionalText`           | `quaternaryText`                       |
+| `presence`               | `presence`                             |
+| `presenceTitle`          | -                                      |
+| `primaryText`            | `primaryText`                          |
+| `secondaryText`          | `secondaryText`                        |
+| `showOverflowTooltip`    | -                                      |
+| `showUnknownPersonaCoin` | -                                      |
+| `styles`                 | `className`                            |
+| `tertiaryText`           | `tertiaryText`                         |
+| `text`                   | `name`                                 |