From da9696e7394adf5d333f007a94405f3c29fa202a Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 20 Mar 2025 10:59:28 +0100 Subject: [PATCH 1/6] docs(migration-guides): reorder migration guides latest version first --- .../v10.0.x-v10.1.x.md | 4 +- .../v10.x-v11.x.md | 2 +- .../v11.6.x-v12.0.x.md | 50 +++++++++++++++++++ .../update-from-grafana-versions/v6.x-v7.x.md | 8 +-- .../update-from-grafana-versions/v7.x-v8.x.md | 6 +-- .../v8.3.x-8.4.x.md | 4 +- .../update-from-grafana-versions/v8.x-v9.x.md | 6 +-- .../v9.1.x-v9.2.x.md | 4 +- .../v9.3.x-9.4.x.md | 6 +-- .../v9.x-v10.x.md | 6 +-- 10 files changed, 73 insertions(+), 23 deletions(-) create mode 100644 docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md index f8a7bbde1..5b3f00d28 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md @@ -1,7 +1,7 @@ --- -id: migrate-10_0_x-to-10_1_x +id: migrate-10_0-to-10_1 title: 10.0.x to 10.1.x -sidebar_position: 1 +sidebar_position: 4 description: How to migrate plugins from Grafana version 10.0.x to 10.1.x. keywords: - grafana diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md index 35eaed0cf..de50eefeb 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.x-v11.x.md @@ -1,7 +1,7 @@ --- id: migrate-10_x-to-11_x title: 10.x to 11.x -sidebar_position: 2 +sidebar_position: 3 description: How to migrate plugins from Grafana version 10.x to 11.x keywords: - grafana diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md new file mode 100644 index 000000000..1f207e0f7 --- /dev/null +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md @@ -0,0 +1,50 @@ +--- +id: migrate-11_6_x-to-12_0_x +title: 11.6.x to 12.0.x +sidebar_position: 1 +description: How to migrate plugins from Grafana version 11.6.x to 12.0.x. +keywords: + - grafana + - plugins + - plugin + - upgrading + - updating + - migration +--- + +# Migrate plugins from Grafana version 11.6.x to 12.0.x + +Follow these instructions to migrate plugins from Grafana version 11.6.x to 12.0.x. + +### Deprecated UI extension APIs removed from @grafana/runtime and @grafana/data + +The deprecated UI extension APIs have been removed in Grafana 12 in favour of the new reactive APIs introduced in Grafana 11.4. These consisted of: + +- `usePluginExtensions()` +- `usePluginLinkExtensions()` +- `usePluginComponentExtensions()` +- `getPluginExtensions()` +- `getPluginLinkExtensions()` +- `getPluginComponentExtensions()` +- `AppPlugin.configureExtensionLink()` and the associated `PluginExtensionLinkConfig` type +- `AppPlugin.configureExtensionComponent()` and the associated `PluginExtensionComponentConfig` type + +Attempting to use any of the above in Grafana 12 will throw an error. + +**Recommended actions:** + +| Deprecated API | Equivalent API | Notes | +| ----------------------------------------- | --------------------------------------------- | ----- | +| `AppPlugin.configureExtensionComponent()` | `AppPlugin.addComponent()` | | +| `AppPlugin.configureExtensionLink()` | `AppPlugin.addLink()` | | +| `getPluginComponentExtensions()` | `usePluginComponents()` | | +| `getPluginExtensions()` | `usePluginLinks()` or `usePluginComponents()` | | +| `getPluginLinkExtensions()` | `usePluginLinks()` | | +| `usePluginComponentExtensions()` | `usePluginComponents()` | | +| `usePluginExtensions()` | `usePluginLinks()` or `usePluginComponents()` | | +| `usePluginLinkExtensions()` | `usePluginLinks()` | | +| `PluginExtensionComponentConfig` | `PluginAddedLinkConfig` | | +| `PluginExtensionLinkConfig` | `PluginExtensionAddedLinkConfig` | | + +**Please note:** +None of this makes any sense to me. diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md index 80d9423b2..04595095b 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md @@ -1,7 +1,7 @@ --- id: migrate-6_x-to-7_0 title: 6.x to 7.0 -sidebar_position: 8 +sidebar_position: 11 description: How to upgrade plugins from Grafana version 6.x to 7.0. keywords: - grafana @@ -30,11 +30,11 @@ Previously, data source plugins could send data either as time series or tables. ### Improved TypeScript support -Although the previous Angular-based plugin SDK supported TypeScript, we’ve greatly improved the support for the React platform. All our APIs are now written in TypeScript, which might require existing code to update to the new stricter type definitions. Grafana 7.0 also introduced several new APIs for plugin developers that take advantage of many of the new features in Grafana 7.0. +Although the previous Angular-based plugin SDK supported TypeScript, we've greatly improved the support for the React platform. All our APIs are now written in TypeScript, which might require existing code to update to the new stricter type definitions. Grafana 7.0 also introduced several new APIs for plugin developers that take advantage of many of the new features in Grafana 7.0. ### Grafana Toolkit -With Grafana 7.0, we released a new tool for making it easier to develop plugins. Before, you’d use Gulp, Grunt, or similar tools to generate the minified assets. Grafana Toolkit takes care of building and testing your plugin without complicated configuration files. +With Grafana 7.0, we released a new tool for making it easier to develop plugins. Before, you'd use Gulp, Grunt, or similar tools to generate the minified assets. Grafana Toolkit takes care of building and testing your plugin without complicated configuration files. For more information, refer to [@grafana/toolkit](https://www.npmjs.com/package/@grafana/toolkit). @@ -54,7 +54,7 @@ For plugins prior to Grafana 7.0, all options are considered _Display options_. While backend plugins were available as an experimental feature in previous versions of Grafana, their support has been greatly improved for Grafana 7. Backend plugins for Grafana 7.0 are backwards-compatible and will continue to work. However, the old backend plugin system has been deprecated, and we recommend that you use the new SDK for backend plugins. -Since Grafana 7.0 introduced signing of backend plugins, community plugins won’t load by default if they’re unsigned. +Since Grafana 7.0 introduced signing of backend plugins, community plugins won't load by default if they're unsigned. ### Migrate to data frames diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md index 92f4905f1..1504cf3a0 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md @@ -1,7 +1,7 @@ --- -id: migrate-7_x-to-8_x -title: 7.x to 8.x -sidebar_position: 7 +id: migrate-7_x-to-8_0 +title: 7.x to 8.0 +sidebar_position: 10 description: How to migrate Grafana v7.x plugins to the updated plugin system available in Grafana v8.x. keywords: - grafana diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md index aa74abf83..db476907c 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md @@ -1,7 +1,7 @@ --- -id: migrate-8_3_x-to-8_4_x +id: migrate-8_3-to-8_4 title: 8.3.x to 8.4.x -sidebar_position: 6 +sidebar_position: 9 description: How to migrate Grafana v8.3.x plugins to Grafana v8.4.x. keywords: - grafana diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md index dffcff544..c0971a69e 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md @@ -1,7 +1,7 @@ --- -id: migrate-8_x-to-9_x -title: 8.x to 9.x -sidebar_position: 5 +id: migrate-8_x-to-9_0 +title: 8.x to 9.0 +sidebar_position: 8 description: How to migrate plugins from version 8.x to 9.x. keywords: - grafana diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md index bb9f8ed3d..22fe57d56 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md @@ -1,7 +1,7 @@ --- -id: migrate-9_1_x-to-9_2_x +id: migrate-9_1-to-9_2 title: 9.1.x to 9.2.x -sidebar_position: 4 +sidebar_position: 7 description: How to migrate plugins from Grafana version 9.1.x to 9.2.x. keywords: - grafana diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md index 558f5d8c0..6cb542d6b 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md @@ -1,7 +1,7 @@ --- -id: migrate-9_3_x-to-9_4_x +id: migrate-9_3-to-9_4 title: 9.3.x to 9.4.x -sidebar_position: 3 +sidebar_position: 6 description: How to migrate from Grafana 9.3.x to 9.4.x. keywords: - grafana @@ -123,7 +123,7 @@ function PluginPageFallback(props: PluginPageProps) { } ``` -There’s an additional step (and `if` block) that is needed to hide or show tabs depending on whether `config.features.topnav` is `true`. Your plugin needs to include these changes in the `useNavModel.ts` file: +There's an additional step (and `if` block) that is needed to hide or show tabs depending on whether `config.features.topnav` is `true`. Your plugin needs to include these changes in the `useNavModel.ts` file: ```tsx // useNavModel.ts diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md index 6c7d80664..f30b8d4a2 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md @@ -1,7 +1,7 @@ --- -id: migrate-9_x-to-10_x -title: 9.x to 10.x -sidebar_position: 2 +id: migrate-9_x-to-10_0 +title: 9.x to 10.0 +sidebar_position: 5 description: How to migrate plugins from Grafana version 9.x to 10.x. keywords: - grafana From a62704e0d87ddc532cb6df4377892ee8d59870b9 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 20 Mar 2025 10:59:51 +0100 Subject: [PATCH 2/6] chore(docusaurus): delete redundant babel config gile --- docusaurus/website/babel.config.js | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 docusaurus/website/babel.config.js diff --git a/docusaurus/website/babel.config.js b/docusaurus/website/babel.config.js deleted file mode 100644 index e00595dae..000000000 --- a/docusaurus/website/babel.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -}; From 99ac9072cfec730dac8340018a4973a219548632 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 20 Mar 2025 17:20:57 +0100 Subject: [PATCH 3/6] docs(website): add migration guide for v11.6.x-v12.0.x --- .../v11.6.x-v12.0.x.md | 145 +++++++++++++++--- 1 file changed, 120 insertions(+), 25 deletions(-) diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md index 1f207e0f7..f7d8b1c5e 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md @@ -14,11 +14,19 @@ keywords: # Migrate plugins from Grafana version 11.6.x to 12.0.x -Follow these instructions to migrate plugins from Grafana version 11.6.x to 12.0.x. +This guide helps you migrate plugins from Grafana version 11.6.x to 12.0.x. -### Deprecated UI extension APIs removed from @grafana/runtime and @grafana/data +## Prerequisites -The deprecated UI extension APIs have been removed in Grafana 12 in favour of the new reactive APIs introduced in Grafana 11.4. These consisted of: +Before starting the migration: + +- Back up your plugin code +- Ensure your development environment is up to date +- Familiarize yourself with the new reactive APIs introduced in Grafana 11.4 + +## Deprecated UI extension APIs removal + +The deprecated UI extension APIs have been removed in Grafana 12 in favor of the new reactive APIs introduced in Grafana 11.4. The following APIs have been removed: - `usePluginExtensions()` - `usePluginLinkExtensions()` @@ -26,25 +34,112 @@ The deprecated UI extension APIs have been removed in Grafana 12 in favour of th - `getPluginExtensions()` - `getPluginLinkExtensions()` - `getPluginComponentExtensions()` -- `AppPlugin.configureExtensionLink()` and the associated `PluginExtensionLinkConfig` type -- `AppPlugin.configureExtensionComponent()` and the associated `PluginExtensionComponentConfig` type - -Attempting to use any of the above in Grafana 12 will throw an error. - -**Recommended actions:** - -| Deprecated API | Equivalent API | Notes | -| ----------------------------------------- | --------------------------------------------- | ----- | -| `AppPlugin.configureExtensionComponent()` | `AppPlugin.addComponent()` | | -| `AppPlugin.configureExtensionLink()` | `AppPlugin.addLink()` | | -| `getPluginComponentExtensions()` | `usePluginComponents()` | | -| `getPluginExtensions()` | `usePluginLinks()` or `usePluginComponents()` | | -| `getPluginLinkExtensions()` | `usePluginLinks()` | | -| `usePluginComponentExtensions()` | `usePluginComponents()` | | -| `usePluginExtensions()` | `usePluginLinks()` or `usePluginComponents()` | | -| `usePluginLinkExtensions()` | `usePluginLinks()` | | -| `PluginExtensionComponentConfig` | `PluginAddedLinkConfig` | | -| `PluginExtensionLinkConfig` | `PluginExtensionAddedLinkConfig` | | - -**Please note:** -None of this makes any sense to me. +- `AppPlugin.configureExtensionLink()` +- `AppPlugin.configureExtensionComponent()` + +Attempting to use any of these APIs in Grafana 12 will throw an error. Additionally, the associated TypeScript types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed. + +:::info +If you need your plugin to work with both Grafana 12.0.x and older versions, you can implement runtime checks to conditionally use the appropriate APIs. For more information, refer to [Manage backwards compatibility with runtime checks](/how-to-guides/runtime-checks.md#example-conditionally-use-react-hooks). +::: + +### AppPlugin.configureExtensionLink() + +Replace the `configureExtensionLink` method with the `addLink` method. Update the `extensionPointId` parameter to `targets`, which accepts either a `string` or `string[]`. + +```diff +- new AppPlugin().configureExtensionLink({ ++ new AppPlugin().addLink({ +- extensionPointId: PluginExtensionPoints.DashboardPanelMenu, ++ targets: PluginExtensionPoints.DashboardPanelMenu, + title: 'Component title 0', + description: 'Component description 0', + component: () =>
, +}); +``` + +### AppPlugin.configureExtensionComponent() + +Replace the `configureExtensionComponent` method with the `addComponent` method. Update the `extensionPointId` parameter to `targets`, which accepts either a `string` or `string[]`. + +```diff +- new AppPlugin().configureExtensionComponent({ ++ new AppPlugin().addComponent({ +- extensionPointId: PluginExtensionPoints.CommandPalette, ++ targets: PluginExtensionPoints.CommandPalette, + title: 'Component title 0', + description: 'Component description 0', + component: () =>
, +}); +``` + +### getPluginLinkExtensions() and usePluginLinkExtensions() + +Both the `getPluginLinkExtensions()` function and the `usePluginLinkExtensions()` React hook can be replaced with the `usePluginLinks()` React hook. + +```diff title="getPluginLinkExtensions" +- const { extensions } = getPluginLinkExtensions({ ++ const { links, isLoading } = usePluginLinks({ + extensionPointId: 'grafana/dashboard/panel/menu/v1', + limitPerPlugin: 2, + context: { + panelId: '...', + }, +}); +``` + +```diff title="usePluginLinkExtensions" +- const { extensions, isLoading } = usePluginLinkExtensions({ ++ const { links, isLoading } = usePluginLinks({ + extensionPointId: 'grafana/dashboard/panel/menu/v1', + limitPerPlugin: 2, + context: { + panelId: '...', + }, +}); +``` + +### getPluginComponentExtensions() and usePluginComponentExtensions() + +Both the `getPluginComponentExtensions()` function and the `usePluginComponentExtensions()` React hook can be replaced with the `usePluginComponents()` React hook. + +```diff title="getPluginComponentExtensions" +- const { extensions } = getPluginComponentExtensions({ ++ const { components, isLoading } = usePluginComponents({ + extensionPointId: 'grafana/user/profile/tab/v1', + limitPerPlugin: 2, +}); +``` + +```diff title="usePluginComponentExtensions" +- const { extensions, isLoading } = usePluginComponentExtensions({ ++ const { components, isLoading } = usePluginComponents({ + extensionPointId: 'grafana/user/profile/tab/v1', + limitPerPlugin: 2, +}); +``` + +### getPluginExtensions() and usePluginExtensions() + +The `getPluginExtensions()` function and the `usePluginExtensions()` React hook can be replaced according to their usage. If the previous implementation was used to fetch links please refer to the instructions above related to [link extensions](#getpluginlinkextensions-and-usepluginlinkextensions). If it was used to fetch components please refer to the instructions above related to [component extensions](#getplugincomponentextensions-and-useplugincomponentextensions). If it was used to fetch both links and extensions, use both `usePluginLinks` and `usePluginComponents`. + +### PluginExtensionLinkConfig and PluginExtensionComponentConfig + +The types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed from `@grafana/data`. If you are using them they should be replaced with `PluginExtensionAddedComponentConfig`and`PluginExtensionAddedLinkConfig` respectively. + +## Quick reference + +The following table summarizes the API changes and their key differences: + +| Deprecated API | Equivalent API | Notes | +| ----------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- | +| `AppPlugin.configureExtensionLink()` | `AppPlugin.addLink()` | `extensionPointId` parameter renamed to `targets`, accepts `string` or `string[]` | +| `AppPlugin.configureExtensionComponent()` | `AppPlugin.addComponent()` | `extensionPointId` parameter renamed to `targets`, accepts `string` or `string[]` | +| `getPluginLinkExtensions()` | `usePluginLinks()` | Returns `{ links, isLoading }` instead of `{ extensions }` | +| `usePluginLinkExtensions()` | `usePluginLinks()` | Returns `{ links, isLoading }` instead of `{ extensions }` | +| `getPluginComponentExtensions()` | `usePluginComponents()` | Returns `{ components, isLoading }` instead of `{ extensions }` | +| `usePluginComponentExtensions()` | `usePluginComponents()` | Returns `{ components, isLoading }` instead of `{ extensions, isLoading }` | +| `getPluginExtensions()` | `usePluginLinks()` or `usePluginComponents()` | Split into two separate hooks based on extension type (links or components) | +| `usePluginExtensions()` | `usePluginLinks()` or `usePluginComponents()` | Split into two separate hooks based on extension type (links or components) | +| `PluginExtensionComponentConfig` | `PluginExtensionAddedComponentConfig` | Updated type definition for component configuration | +| `PluginExtensionLinkConfig` | `PluginExtensionAddedLinkConfig` | Updated type definition for link configuration | From e34fd56be531fa31070366454c5de410f72871ae Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 20 Mar 2025 17:34:22 +0100 Subject: [PATCH 4/6] revert(website): put back unnecessary docs changes due to cursor --- .../update-from-grafana-versions/v10.0.x-v10.1.x.md | 2 +- .../update-from-grafana-versions/v11.6.x-v12.0.x.md | 2 +- .../update-from-grafana-versions/v6.x-v7.x.md | 6 +++--- .../update-from-grafana-versions/v7.x-v8.x.md | 4 ++-- .../update-from-grafana-versions/v8.3.x-8.4.x.md | 2 +- .../update-from-grafana-versions/v8.x-v9.x.md | 4 ++-- .../update-from-grafana-versions/v9.1.x-v9.2.x.md | 2 +- .../update-from-grafana-versions/v9.3.x-9.4.x.md | 4 ++-- .../update-from-grafana-versions/v9.x-v10.x.md | 4 ++-- 9 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md index 5b3f00d28..33567493b 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v10.0.x-v10.1.x.md @@ -1,5 +1,5 @@ --- -id: migrate-10_0-to-10_1 +id: migrate-10_0_x-to-10_1_x title: 10.0.x to 10.1.x sidebar_position: 4 description: How to migrate plugins from Grafana version 10.0.x to 10.1.x. diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md index f7d8b1c5e..e2b1059d4 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md @@ -129,7 +129,7 @@ The types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have ## Quick reference -The following table summarizes the API changes and their key differences: +The following table summarizes the API changes with notes explaining the key differences: | Deprecated API | Equivalent API | Notes | | ----------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- | diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md index 04595095b..99b2362ae 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v6.x-v7.x.md @@ -30,11 +30,11 @@ Previously, data source plugins could send data either as time series or tables. ### Improved TypeScript support -Although the previous Angular-based plugin SDK supported TypeScript, we've greatly improved the support for the React platform. All our APIs are now written in TypeScript, which might require existing code to update to the new stricter type definitions. Grafana 7.0 also introduced several new APIs for plugin developers that take advantage of many of the new features in Grafana 7.0. +Although the previous Angular-based plugin SDK supported TypeScript, we’ve greatly improved the support for the React platform. All our APIs are now written in TypeScript, which might require existing code to update to the new stricter type definitions. Grafana 7.0 also introduced several new APIs for plugin developers that take advantage of many of the new features in Grafana 7.0. ### Grafana Toolkit -With Grafana 7.0, we released a new tool for making it easier to develop plugins. Before, you'd use Gulp, Grunt, or similar tools to generate the minified assets. Grafana Toolkit takes care of building and testing your plugin without complicated configuration files. +With Grafana 7.0, we released a new tool for making it easier to develop plugins. Before, you’d use Gulp, Grunt, or similar tools to generate the minified assets. Grafana Toolkit takes care of building and testing your plugin without complicated configuration files. For more information, refer to [@grafana/toolkit](https://www.npmjs.com/package/@grafana/toolkit). @@ -54,7 +54,7 @@ For plugins prior to Grafana 7.0, all options are considered _Display options_. While backend plugins were available as an experimental feature in previous versions of Grafana, their support has been greatly improved for Grafana 7. Backend plugins for Grafana 7.0 are backwards-compatible and will continue to work. However, the old backend plugin system has been deprecated, and we recommend that you use the new SDK for backend plugins. -Since Grafana 7.0 introduced signing of backend plugins, community plugins won't load by default if they're unsigned. +Since Grafana 7.0 introduced signing of backend plugins, community plugins won’t load by default if they’re unsigned. ### Migrate to data frames diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md index 1504cf3a0..056b6e016 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v7.x-v8.x.md @@ -1,6 +1,6 @@ --- -id: migrate-7_x-to-8_0 -title: 7.x to 8.0 +id: migrate-7_x-to-8_x +title: 7.x to 8.x sidebar_position: 10 description: How to migrate Grafana v7.x plugins to the updated plugin system available in Grafana v8.x. keywords: diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md index db476907c..4c26e1dfc 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.3.x-8.4.x.md @@ -1,5 +1,5 @@ --- -id: migrate-8_3-to-8_4 +id: migrate-8_3_x-to-8_4_x title: 8.3.x to 8.4.x sidebar_position: 9 description: How to migrate Grafana v8.3.x plugins to Grafana v8.4.x. diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md index c0971a69e..c582a4c36 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v8.x-v9.x.md @@ -1,6 +1,6 @@ --- -id: migrate-8_x-to-9_0 -title: 8.x to 9.0 +id: migrate-8_x-to-9_x +title: 8.x to 9.x sidebar_position: 8 description: How to migrate plugins from version 8.x to 9.x. keywords: diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md index 22fe57d56..5b51944f2 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.1.x-v9.2.x.md @@ -1,5 +1,5 @@ --- -id: migrate-9_1-to-9_2 +id: migrate-9_1_x-to-9_2_x title: 9.1.x to 9.2.x sidebar_position: 7 description: How to migrate plugins from Grafana version 9.1.x to 9.2.x. diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md index 6cb542d6b..c0c59e7a1 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.3.x-9.4.x.md @@ -1,5 +1,5 @@ --- -id: migrate-9_3-to-9_4 +id: migrate-9_3_x-to-9_4_x title: 9.3.x to 9.4.x sidebar_position: 6 description: How to migrate from Grafana 9.3.x to 9.4.x. @@ -123,7 +123,7 @@ function PluginPageFallback(props: PluginPageProps) { } ``` -There's an additional step (and `if` block) that is needed to hide or show tabs depending on whether `config.features.topnav` is `true`. Your plugin needs to include these changes in the `useNavModel.ts` file: +There’s an additional step (and `if` block) that is needed to hide or show tabs depending on whether `config.features.topnav` is `true`. Your plugin needs to include these changes in the `useNavModel.ts` file: ```tsx // useNavModel.ts diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md index f30b8d4a2..8ce2d46bd 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v9.x-v10.x.md @@ -1,6 +1,6 @@ --- -id: migrate-9_x-to-10_0 -title: 9.x to 10.0 +id: migrate-9_x-to-10_x +title: 9.x to 10.x sidebar_position: 5 description: How to migrate plugins from Grafana version 9.x to 10.x. keywords: From 1409683aa8ed9734bb3954ee3c5ae3384083e750 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 3 Apr 2025 12:52:21 +0200 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Joseph Perez <45749060+josmperez@users.noreply.github.com> --- .../v11.6.x-v12.0.x.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md index e2b1059d4..13e4f9afe 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md @@ -37,7 +37,7 @@ The deprecated UI extension APIs have been removed in Grafana 12 in favor of the - `AppPlugin.configureExtensionLink()` - `AppPlugin.configureExtensionComponent()` -Attempting to use any of these APIs in Grafana 12 will throw an error. Additionally, the associated TypeScript types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed. +Using any of these APIs in Grafana 12 will result in an error. Additionally, the TypeScript types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed. :::info If you need your plugin to work with both Grafana 12.0.x and older versions, you can implement runtime checks to conditionally use the appropriate APIs. For more information, refer to [Manage backwards compatibility with runtime checks](/how-to-guides/runtime-checks.md#example-conditionally-use-react-hooks). @@ -101,7 +101,7 @@ Both the `getPluginLinkExtensions()` function and the `usePluginLinkExtensions() ### getPluginComponentExtensions() and usePluginComponentExtensions() -Both the `getPluginComponentExtensions()` function and the `usePluginComponentExtensions()` React hook can be replaced with the `usePluginComponents()` React hook. +You can replace both the `getPluginComponentExtensions()` function and the `usePluginComponentExtensions()` React hook with the `usePluginComponents()` React hook. ```diff title="getPluginComponentExtensions" - const { extensions } = getPluginComponentExtensions({ @@ -121,11 +121,17 @@ Both the `getPluginComponentExtensions()` function and the `usePluginComponentEx ### getPluginExtensions() and usePluginExtensions() -The `getPluginExtensions()` function and the `usePluginExtensions()` React hook can be replaced according to their usage. If the previous implementation was used to fetch links please refer to the instructions above related to [link extensions](#getpluginlinkextensions-and-usepluginlinkextensions). If it was used to fetch components please refer to the instructions above related to [component extensions](#getplugincomponentextensions-and-useplugincomponentextensions). If it was used to fetch both links and extensions, use both `usePluginLinks` and `usePluginComponents`. +Replace the `getPluginExtensions()` function and the `usePluginExtensions()` React hook based on their usage: + +- **For links:** Follow the [link extensions](https://github.com/grafana/plugin-tools/pull/1639/files#getpluginlinkextensions-and-usepluginlinkextensions) instructions. + +- **For components:** Follow the [component extensions](https://github.com/grafana/plugin-tools/pull/1639/files#getplugincomponentextensions-and-useplugincomponentextensions) instructions. + +- **For both links and components:** Use both `usePluginLinks` and `usePluginComponents`. ### PluginExtensionLinkConfig and PluginExtensionComponentConfig -The types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed from `@grafana/data`. If you are using them they should be replaced with `PluginExtensionAddedComponentConfig`and`PluginExtensionAddedLinkConfig` respectively. +The types `PluginExtensionLinkConfig` and `PluginExtensionComponentConfig` have been removed from `@grafana/data`.Replace them with `PluginExtensionAddedLinkConfig` and `PluginExtensionAddedComponentConfig`, respectively. ## Quick reference From a876b499334f3200208f8edf94d6b8855204a1ee Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Thu, 3 Apr 2025 12:55:50 +0200 Subject: [PATCH 6/6] docs(migration-guides): update g12 migration guide to include link to extensions api docs --- .../update-from-grafana-versions/v11.6.x-v12.0.x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md index 13e4f9afe..1cbe47cfb 100644 --- a/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md +++ b/docusaurus/docs/migration-guides/update-from-grafana-versions/v11.6.x-v12.0.x.md @@ -22,7 +22,7 @@ Before starting the migration: - Back up your plugin code - Ensure your development environment is up to date -- Familiarize yourself with the new reactive APIs introduced in Grafana 11.4 +- Familiarize yourself with [the reactive APIs](/how-to-guides/ui-extensions/) introduced in Grafana 11.4 ## Deprecated UI extension APIs removal