From d0f8adae04e2232866cbf27ac5c421817a9b5e35 Mon Sep 17 00:00:00 2001 From: Marcus Olsson Date: Tue, 8 Dec 2020 10:41:33 +0100 Subject: [PATCH] Docs: Plugin schema updates (#28232) * WIP * Update plugin metadata schema * Fix review comments * Update descriptions * Add description * Fix review comment --- docs/sources/developers/plugins/metadata.md | 83 ++++++++------ .../developers/plugins/plugin.schema.json | 106 ++++++++++++------ 2 files changed, 123 insertions(+), 66 deletions(-) diff --git a/docs/sources/developers/plugins/metadata.md b/docs/sources/developers/plugins/metadata.md index 1a6dad06ea3..0885fa2e320 100644 --- a/docs/sources/developers/plugins/metadata.md +++ b/docs/sources/developers/plugins/metadata.md @@ -15,60 +15,69 @@ The plugin.json file is required for all plugins. When Grafana starts, it scans | Property | Type | Required | Description | |-----------------|-------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `dependencies` | [object](#dependencies) | **Yes** | Plugin dependencies. | +| `dependencies` | [object](#dependencies) | **Yes** | Dependencies needed by the plugin. | | `id` | string | **Yes** | Unique name of the plugin. If the plugin is published on grafana.com, then the plugin id has to follow the naming conventions. | | `info` | [object](#info) | **Yes** | Metadata for the plugin. Some fields are used on the plugins page in Grafana and others on grafana.com if the plugin is published. | | `name` | string | **Yes** | Human-readable name of the plugin that is shown to the user in the UI. | -| `type` | string | **Yes** | Plugin type. Possible values are `app`, `datasource`, and `panel`. | +| `type` | string | **Yes** | Plugin type. Possible values are: `app`, `datasource`, `panel`. | | `$schema` | string | No | Schema definition for the plugin.json file | | `alerting` | boolean | No | For data source plugins. If the plugin supports alerting. | | `annotations` | boolean | No | For data source plugins. If the plugin supports annotation queries. | | `backend` | boolean | No | If the plugin has a backend component. | -| `category` | string | No | Plugin category used on the Add data source page. Possible values are: `tsdb`, `logging`, `cloud`, `tracing`, `sql`, `enterprise` and `other`. | +| `category` | string | No | Plugin category used on the Add data source page. Possible values are: `tsdb`, `logging`, `cloud`, `tracing`, `sql`, `enterprise`, `other`. | | `executable` | string | No | The first part of the file name of the backend component executable. There can be multiple executables built for different operating system and architecture. Grafana will check for executables named `_<$GOOS>_<.exe for Windows>`, e.g. `plugin_linux_amd64`. Combination of $GOOS and $GOARCH can be found here: https://golang.org/doc/install/source#environment. | | `hiddenQueries` | boolean | No | | -| `includes` | [object](#includes)[] | No | | +| `includes` | [object](#includes)[] | No | Resources to include in plugin. | | `logs` | boolean | No | For data source plugins. If the plugin supports logs. | | `metrics` | boolean | No | For data source plugins. If the plugin supports metric queries. Used in the Explore feature. | -| `mixed` | boolean | No | Not to be used by external plugins. Special property for the built-in mixed plugin. | -| `module` | string | No | | -| `partials` | [object](#partials) | No | | | `preload` | boolean | No | Initialize plugin on startup. By default, the plugin initializes on first use. | | `queryOptions` | [object](#queryoptions) | No | For data source plugins. There is a query options section in the plugin's query editor and these options can be turned on if needed. | | `routes` | [object](#routes)[] | No | For data source plugins. Proxy routes used for plugin authentication and adding headers to HTTP requests made by the plugin. For more information, refer to [Authentication for data source plugins](https://grafana.com/docs/grafana/latest/developers/plugins/authentication/). | | `skipDataQuery` | boolean | No | For panel plugins. Hides the query editor. | -| `sort` | number | No | Internal property for sorting. Cannot be used as will be overwritten by Grafana. | -| `state` | string | No | Marks a plugin as a pre-release. | -| `staticRoot` | string | No | | +| `state` | string | No | Marks a plugin as a pre-release. Possible values are: `alpha`, `beta`. | | `streaming` | boolean | No | For data source plugins. If the plugin supports streaming. | | `tables` | boolean | No | | | `tracing` | boolean | No | For data source plugins. If the plugin supports tracing. | ## dependencies -Plugin dependencies. +Dependencies needed by the plugin. ### Properties -| Property | Type | Required | Description | -|---------------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------| -| `grafanaDependency` | string | **Yes** | Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver. | -| `grafanaVersion` | string | No | (Deprecated) Required Grafana version for this plugin, e.g. `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or v7.x.x. | -| `plugins` | string[] | No | An array of required plugins on which this plugin depends. | +| Property | Type | Required | Description | +|---------------------|----------------------|----------|-------------------------------------------------------------------------------------------------------------------------------| +| `grafanaDependency` | string | **Yes** | Required Grafana version for this plugin. Validated using https://github.com/npm/node-semver. | +| `grafanaVersion` | string | No | (Deprecated) Required Grafana version for this plugin, e.g. `6.x.x 7.x.x` to denote plugin requires Grafana v6.x.x or v7.x.x. | +| `plugins` | [object](#plugins)[] | No | An array of required plugins on which this plugin depends. | + +### plugins + +Plugin dependency. Used to display information about plugin dependencies in the Grafana UI. + +#### Properties + +| Property | Type | Required | Description | +|-----------|--------|----------|----------------------------------------------------| +| `id` | string | **Yes** | | +| `name` | string | **Yes** | | +| `type` | string | **Yes** | Possible values are: `app`, `datasource`, `panel`. | +| `version` | string | **Yes** | | ## includes ### Properties -| Property | Type | Required | Description | -|--------------|---------|----------|-------------| -| `addToNav` | boolean | No | | -| `component` | string | No | | -| `defaultNav` | boolean | No | | -| `name` | string | No | | -| `role` | string | No | | -| `type` | string | No | | -| `icon` | string | No | | +| Property | Type | Required | Description | +|--------------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `addToNav` | boolean | No | Add the include to the side menu. | +| `component` | string | No | (Legacy) The Angular component to use for a page. | +| `defaultNav` | boolean | No | Page or dashboard when user clicks the icon in the side menu. | +| `icon` | string | No | Icon to use in the side menu. For information on available icon, refer to [Icons Overview](https://developers.grafana.com/ui/latest/index.html?path=/story/docs-overview-icon--icons-overview). | +| `name` | string | No | | +| `path` | string | No | Used for app plugins. | +| `role` | string | No | Possible values are: `Admin`, `Editor`, `Viewer`. | +| `type` | string | No | Possible values are: `dashboard`, `page`, `panel`, `datasource`. | ## info @@ -83,6 +92,7 @@ Metadata for the plugin. Some fields are used on the plugins page in Grafana and | `updated` | string | **Yes** | Date when this plugin was built. | | `version` | string | **Yes** | Project version of this commit, e.g. `6.7.x`. | | `author` | [object](#author) | No | Information about the plugin author. | +| `build` | [object](#build) | No | Build information | | `description` | string | No | Description of plugin. Used on the plugins page in Grafana and for search on grafana.com. | | `links` | [object](#links)[] | No | An array of link objects to be displayed on this plugin's project page in the form `{name: 'foo', url: 'http://example.com'}` | | `screenshots` | [object](#screenshots)[] | No | An array of screenshot objects in the form `{name: 'bar', path: 'img/screenshot.png'}` | @@ -99,6 +109,21 @@ Information about the plugin author. | `name` | string | No | Author's name. | | `url` | string | No | Link to author's website. | +### build + +Build information + +#### Properties + +| Property | Type | Required | Description | +|----------|--------|----------|------------------------------------------------------| +| `branch` | string | No | Git branch the plugin was built from. | +| `hash` | string | No | Git hash of the commit the plugin was built from | +| `number` | number | No | | +| `pr` | number | No | GitHub pull request the plugin was built from | +| `repo` | string | No | | +| `time` | number | No | Time when the plugin was built, as a Unix timestamp. | + ### links #### Properties @@ -128,14 +153,6 @@ SVG images that are used as plugin icons. | `name` | string | No | | | `path` | string | No | | -## partials - -### Properties - -| Property | Type | Required | Description | -|----------|--------|----------|-------------| -| `config` | string | No | | - ## queryOptions For data source plugins. There is a query options section in the plugin's query editor and these options can be turned on if needed. diff --git a/docs/sources/developers/plugins/plugin.schema.json b/docs/sources/developers/plugins/plugin.schema.json index fd9163766f0..1496c6856d2 100644 --- a/docs/sources/developers/plugins/plugin.schema.json +++ b/docs/sources/developers/plugins/plugin.schema.json @@ -18,7 +18,7 @@ }, "type": { "type": "string", - "description": "Plugin type. Possible values are `app`, `datasource`, and `panel`.", + "description": "Plugin type.", "enum": ["app", "datasource", "panel"] }, "name": { @@ -27,7 +27,7 @@ }, "category": { "type": "string", - "description": "Plugin category used on the Add data source page. Possible values are: `tsdb`, `logging`, `cloud`, `tracing`, `sql`, `enterprise` and `other`.", + "description": "Plugin category used on the Add data source page.", "enum": ["tsdb", "logging", "cloud", "tracing", "sql", "enterprise", "other"] }, "annotations": { @@ -57,27 +57,41 @@ }, "includes": { "type": "array", + "description": "Resources to include in plugin.", "items": { "type": "object", "additionalItems": false, "properties": { "type": { - "type": "string" + "type": "string", + "enum": ["dashboard", "page", "panel", "datasource"] }, "name": { "type": "string" }, "component": { - "type": "string" + "type": "string", + "description": "(Legacy) The Angular component to use for a page." }, "role": { - "type": "string" + "type": "string", + "enum": ["Admin", "Editor", "Viewer"] + }, + "path": { + "type": "string", + "description": "Used for app plugins." }, "addToNav": { - "type": "boolean" + "type": "boolean", + "description": "Add the include to the side menu." }, "defaultNav": { - "type": "boolean" + "type": "boolean", + "description": "Page or dashboard when user clicks the icon in the side menu." + }, + "icon": { + "type": "string", + "description": "Icon to use in the side menu. For information on available icon, refer to [Icons Overview](https://developers.grafana.com/ui/latest/index.html?path=/story/docs-overview-icon--icons-overview)." } } } @@ -90,34 +104,10 @@ "type": "boolean", "description": "For panel plugins. Hides the query editor." }, - "partials": { - "type": "object", - "additionalItems": false, - "properties": { - "config": { - "type": "string" - } - } - }, "metrics": { "type": "boolean", "description": "For data source plugins. If the plugin supports metric queries. Used in the Explore feature." }, - "mixed": { - "type": "boolean", - "description": "Not to be used by external plugins. Special property for the built-in mixed plugin." - }, - "module": { - "type": "string", - "description": "" - }, - "sort": { - "type": "number", - "description": "Internal property for sorting. Cannot be used as will be overwritten by Grafana." - }, - "staticRoot": { - "type": "string" - }, "streaming": { "type": "boolean", "description": "For data source plugins. If the plugin supports streaming." @@ -134,7 +124,7 @@ }, "dependencies": { "type": "object", - "description": "Plugin dependencies.", + "description": "Dependencies needed by the plugin.", "required": ["grafanaDependency"], "additionalProperties": false, "properties": { @@ -151,8 +141,27 @@ "plugins": { "type": "array", "description": "An array of required plugins on which this plugin depends.", + "additionalItems": false, "items": { - "type": "string" + "type": "object", + "description": "Plugin dependency. Used to display information about plugin dependencies in the Grafana UI.", + "required": ["id", "name", "type", "version"], + "properties": { + "id": { + "type": "string", + "pattern": "^[0-9a-z]+\\-([0-9a-z]+\\-)?(app|panel|datasource)$" + }, + "type": { + "type": "string", + "enum": ["app", "datasource", "panel"] + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + } + } } } } @@ -184,6 +193,37 @@ } } }, + "build": { + "type": "object", + "description": "Build information", + "additionalProperties": false, + "properties": { + "time": { + "type": "number", + "description": "Time when the plugin was built, as a Unix timestamp." + }, + "repo": { + "type": "string", + "description": "" + }, + "branch": { + "type": "string", + "description": "Git branch the plugin was built from." + }, + "hash": { + "type": "string", + "description": "Git hash of the commit the plugin was built from" + }, + "number": { + "type": "number", + "description": "" + }, + "pr": { + "type": "number", + "description": "GitHub pull request the plugin was built from" + } + } + }, "description": { "type": "string", "description": "Description of plugin. Used on the plugins page in Grafana and for search on grafana.com."