Updating migration docs and adding hint about polystat panel (#51367)

2025-02-25 18:55:37 -06:00 · 2022-06-27 09:43:35 +02:00 · 2022-06-27 09:43:35 +02:00 · cb17f91ab5
commit cb17f91ab5
parent 7f0c33d8a4
2 changed files with 115 additions and 2 deletions
--- a/docs/sources/developers/plugins/migration-guide.md
+++ b/docs/sources/developers/plugins/migration-guide.md
@ -8,7 +8,7 @@ title: Plugin migration guide

 ## Introduction

-This guide helps you identify the steps you need to take based on the Grafana version your plugin supports and explains how to migrate the plugin to the 8.2.x or a later version.
+This guide helps you identify the steps required to update a plugin from the Grafana version it currently supports to newer versions of Grafana.

 > **Note:** If you've successfully migrated your plugin using this guide, then share your experiences with us! If you find missing information, then we encourage you to [submit an issue on GitHub](https://github.com/grafana/grafana/issues/new?title=Docs%20feedback:%20/developers/plugins/migration-guide.md) so that we can improve this guide!

@ -17,6 +17,15 @@ This guide helps you identify the steps you need to take based on the Grafana ve
 - [Plugin migration guide](#plugin-migration-guide)
  - [Introduction](#introduction)
  - [Table of contents](#table-of-contents)
+  - [From version 8.x to 9.x](#from-version-8x-to-9x)
+    - [9.0 breaking changes](#90-breaking-changes)
+      - [theme.visualization.getColorByName replaces getColorForTheme](#themevisualizationgetcolorbyname-replaces-getcolorfortheme)
+      - [VizTextDisplayOptions replaces TextDisplayOptions](#viztextdisplayoptions-replaces-textdisplayoptions)
+      - [Changes in the internal of `backendSrv.fetch()`](#changes-in-the-internal-of-backendsrvfetch)
+      - [GrafanaTheme2 and useStyles2 replaces getFormStyles](#grafanatheme2-and-usestyles2-replaces-getformstyles)
+      - [/api/ds/query replaces /api/tsdb/query](#apidsquery-replaces-apitsdbquery)
+      - [selectOptionInTest has been removed](#selectoptionintest-has-been-removed)
+      - [Toolkit 9 and webpack](#toolkit-9-and-webpack)
  - [From version 8.3.x to 8.4.x](#from-version-83x-to-84x)
    - [Value Mapping Editor has been removed from @grafana-ui library](#value-mapping-editor-has-been-removed-from-grafana-ui-library)
    - [Thresholds Editor has been removed from @grafana-ui library](#thresholds-editor-has-been-removed-from-grafana-ui-library)
@ -51,6 +60,106 @@ This guide helps you identify the steps you need to take based on the Grafana ve
      - [Migrate to data frames](#migrate-to-data-frames)
    - [Troubleshoot plugin migration](#troubleshoot-plugin-migration)

+## From version 8.x to 9.x
+
+### 9.0 breaking changes
+
+#### theme.visualization.getColorByName replaces getColorForTheme
+
+`getColorForTheme` was removed, use `theme.visualization.getColorByName` instead
+
+Example:
+
+```ts
+// before
+fillColor: getColorForTheme(panel.sparkline.fillColor, config.theme)
+
+// after
+fillColor: config.theme.visualization.getColorByName(panel.sparkline.fillColor),
+```
+
+#### VizTextDisplayOptions replaces TextDisplayOptions
+
+`TextDisplayOptions` was removed, use `VizTextDisplayOptions` instead
+
+Example:
+
+```ts
+// before
+interface Options {
+...
+text?: TextDisplayOptions;
+...
+}
+
+// after
+interface Options {
+...
+text?: VizTextDisplayOptions;
+...
+}
+```
+
+#### Changes in the internal of `backendSrv.fetch()`
+
+We have changed the internals of `backendSrv.fetch()` to throw an error when the response is an incorrect JSON. Make sure to handle possible errors on the callsite where using `backendSrv.fetch()` (or any other `backendSrv` methods)
+
+```ts
+// PREVIOUSLY: this was returning with an empty object {} - in case the response is an invalid JSON
+return await getBackendSrv().post(`${API_ROOT}/${id}/install`);
+
+// AFTER THIS CHANGE: the following will throw an error - in case the response is an invalid JSON
+return await getBackendSrv().post(`${API_ROOT}/${id}/install`);
+```
+
+#### GrafanaTheme2 and useStyles2 replaces getFormStyles
+
+We have removed the deprecated `getFormStyles` function from [grafana-ui](https://www.npmjs.com/package/@grafana/ui). Use `GrafanaTheme2` and the `useStyles2` hook instead
+
+#### /api/ds/query replaces /api/tsdb/query
+
+We have removed the deprecated `/api/tsdb/query` metrics endpoint. Use [/api/ds/query]({{< relref "../http_api/data_source/#query-a-data-source" >}}) instead
+
+#### selectOptionInTest has been removed
+
+The `@grafana/ui` package helper function `selectOptionInTest` used in frontend tests has been removed as it caused testing libraries to be bundled in the production code of Grafana. If you were using this helper function in your tests please update your code accordingly:
+
+```ts
+// before
+import { selectOptionInTest } from '@grafana/ui';
+// ...test usage
+await selectOptionInTest(selectEl, 'Option 2');
+
+// after
+import { select } from 'react-select-event';
+// ...test usage
+await select(selectEl, 'Option 2', { container: document.body });
+```
+
+#### Toolkit 9 and webpack
+
+Plugins using custom Webpack configs could potentially break due to the changes between webpack@4 and webpack@5. Please refer to the [official migration guide](https://webpack.js.org/migrate/5/) for assistance.
+
+Webpack 5 does not include polyfills for node.js core modules by default (e.g. `buffer`, `stream`, `os`). This can result in failed builds for plugins. If polyfills are required it is recommended to create a custom webpack config in the root of the plugin repo and add the required fallbacks:
+
+```js
+// webpack.config.js
+
+module.exports.getWebpackConfig = (config, options) => ({
+  ...config,
+  resolve: {
+    ...config.resolve,
+    fallback: {
+      os: require.resolve('os-browserify/browser'),
+      stream: require.resolve('stream-browserify'),
+      timers: require.resolve('timers-browserify'),
+    },
+  },
+});
+```
+
+Please refer to the webpack build error messages or the [official migration guide](https://webpack.js.org/migrate/5/) for assistance with fallbacks.
+
 ## From version 8.3.x to 8.4.x

 This section explains how to migrate Grafana v8.3.x plugins to the updated plugin system available in Grafana v8.4.x. Depending on your plugin, you need to perform one or more of the following steps.
--- a/docs/sources/whatsnew/whats-new-in-v9-0.md
+++ b/docs/sources/whatsnew/whats-new-in-v9-0.md
@ -218,7 +218,11 @@ The rename by regex transformation has been improved to allow global patterns of

 ### Clock Panel

-We have updated [clock panel](https://grafana.com/grafana/plugins/grafana-clock-panel/) to version `2.0.0` to make it Compatible with Grafana 9. The previous version `1.3.1` will cause the Grafana 9 to [crash](https://github.com/grafana/clock-panel/issues/106) when being used in a dashboard, we encourage you to update the panel before migrating to Grafana 9.
+We have updated [clock panel](https://grafana.com/grafana/plugins/grafana-clock-panel/) to version `2.0.0` to make it compatible with Grafana 9. The previous version `1.3.1` will cause the Grafana 9 to [crash](https://github.com/grafana/clock-panel/issues/106) when being used in a dashboard, we encourage you to update the panel before migrating to Grafana 9.
+
+### Polystat Panel
+
+We have updated [polystat panel](https://grafana.com/grafana/plugins/grafana-polystat-panel/) to version `1.2.10` to make it compatible with Grafana 9. The previous versions `1.2.8` and below will render empty in Grafana 9. We encourage you to update the panel before or immediately after migrating to Grafana 9.

 ### Plugins: Most relevant breaking changes