Docs: Add documentation about setMigrationHandler for panels #1213
Conversation
|
Hello! 👋 This repository uses Auto for releasing packages using PR labels. ✨ This PR can be merged. It will not be considered when calculating future versions of the npm packages and will not appear in the changelogs. |
academo
added
type/docs
|
|
||
| # Add a migration handler to your panel plugin | ||
|
|
||
| As you develop and maintain your Grafana panel plugin, you may need to make changes to the panel options structure. These changes can potentially break existing dashboard configurations. |
There was a problem hiding this comment.
I'd mention that if breaking changes exist, the major version should be bumped and migration guidance should be provided.
| } | ||
| ``` | ||
|
|
||
| ### Version-specific adjustments |
There was a problem hiding this comment.
maybe also an example to check the plugin version? something like:
const pluginVersion = panel?.pluginVersion ?? '';
if (pluginVersion.startsWith('1.0')) {
// Do migration
}| The migration handler is only called when the stored panel version differs from the loaded panel version. (e.g. after an update) | ||
|
|
||
| The migration handler will be called until the user manually edits and saves the panel. |
There was a problem hiding this comment.
maybe...
| The migration handler is only called when the stored panel version differs from the loaded panel version. (e.g. after an update) | |
| The migration handler will be called until the user manually edits and saves the panel. | |
| The migration handler is only called when the installed plugin version differs from the version used to generate a panel. Changes made to the panel are not automatically persisted, users need to manually save the dashboard after a panel is migrated. |
| @@ -0,0 +1,151 @@ | |||
| --- | |||
| id: migration-handler-for-panels | |||
There was a problem hiding this comment.
not sure how to structure this but I was thinking on a generic page with general information about plugin migrations (e.g. when to use it) and then split in different pages:
- Migrations for panel plugins
- Migration for frontend datasources
- Migration for backend datasources
- (Maybe in the future?) Migration for apps
I guess this is fine for the first guide but we may need to restructure?
What this PR does / why we need it:
Adds a documentation page for the
setMigrationHandlersfor panels.Which issue(s) this PR fixes:
closes #1128
Special notes for your reviewer: