Add more information on kibana.json properties, update example plugins (

elastic#107600) * Add more information on kibana.json properties, update example plugin kibana.jsons * fix auto save fix * Update anatomy_of_a_plugin.mdx * Update anatomy_of_a_plugin.mdx * update based on review comments * Update anatomy_of_a_plugin.mdx * Put kibanaVersion back and adjust the explanations of the fields Co-authored-by: Kibana Machine <[email protected]>
dominiqueclarke · Aug 9, 2021 · b9f3988 · b9f3988
1 parent dcd628b
commit b9f3988
Show file tree

Hide file tree

Showing 17 changed files with 132 additions and 44 deletions.
diff --git a/dev_docs/tutorials/building_a_plugin.mdx → ...docs/key_concepts/anatomy_of_a_plugin.mdx b/dev_docs/tutorials/building_a_plugin.mdx → ...docs/key_concepts/anatomy_of_a_plugin.mdx
@@ -1,13 +1,13 @@
 ---
 id: kibDevTutorialBuildAPlugin
-slug: /kibana-dev-docs/tutorials/build-a-plugin
-title: Kibana plugin tutorial
-summary: Anatomy of a Kibana plugin and how to build one
-date: 2021-02-05
-tags: ['kibana', 'onboarding', 'dev', 'tutorials']
+slug: /kibana-dev-docs/tutorials/anatomy-of-a-plugin
+title: Anatomy of a plugin
+summary: Anatomy of a Kibana plugin.
+date: 2021-08-03
+tags: ['kibana', 'onboarding', 'dev']
 ---
 
-Prereading material:
+Pre-reading material:
 
 - <DocLink id="kibPlatformIntro" />
 
@@ -39,27 +39,50 @@ plugins/
 
 ```
 {
-  "id": "demo",
-  "version": "kibana",
+  "id": "examplePluginId",
+  "version": "1.0.0",
+  "kibanaVersion": "7.14.0",
   "server": true,
   "ui": true,
-  "owner": { [1]
+  "configPath": "path/to/config",
+  "type": "standard",
+  "owner": {
     "name": "App Services",
     "githubTeam": "kibana-app-services"
   },
-  "description": "This plugin extends Kibana by doing xyz, and allows other plugins to extend Kibana by offering abc functionality. It also exposes some helper utilities that do efg", [2]
-  "requiredPlugins": ["data"], [3]
-  "optionalPlugins": ["alerting"] [4]
-  "requiredBundles": ["anotherPlugin"] [5]
+  "description": "A description about this plugin!",
+  "requiredPlugins": ["data"],
+  "optionalPlugins": ["alerting"]
+  "requiredBundles": ["anotherPlugin"]
 }
 ```
 
-[1], [2]: Every internal plugin should fill in the owner and description properties.
+`id` - [Required] The id of your plugin can be anything, though it should be fairly unique, as every plugin in an installation needs to be unique. It must be snakeCase.
+
+`version` - [Required] Note the version of your plugin. For internal plugins that don't specify a `kibanaVersion`, this will have to match the version of Kibana or ci will fail. Because teams won't want to be bumping this number for every release, internal plugins should set `kibanaVersion` to "kibana", and set this to anything.
+
+`kibanaVersion` - [Optional] If your plugin is only compatible with a specific version of Kibana, put it here. Internal, first-party plugins should set this to "kibana", otherwise they will need to bump this value, or the one in `version`, every time the Kibana version is bumped. When [#61087](https://github.com/elastic/kibana/issues/61087) is fixed, we will stop requiring this field for internal plugins.
+
+`server` - [Optional] If your plugin contains server-side code, this must be true.
+
+`ui` - [Optional] If your plugin contains client-side code, this must be true.
+
+`configPath` - [Optional] Every plugin might allow Kibana users to adjust configuration via kibana.yml file. If your plugin needs to read config from `kibana.yml , you should declare what property name it should have access to.
+
+`type` - [Optional] Should be either `preboot` or `standard` which specifies the type of plugin. Default value, if unspecified, is `standard`. There are two types of plugins:
+
+- preboot plugins are bootstrapped to prepare the environment before Kibana starts.
+- standard plugins define Kibana functionality while Kibana is running.
+
+`owner` - [Required] Help users of your plugin know who manages this plugin and how to get in touch. This is required for internal plugins. `Owner.name` should be the name of the team that manages this plugin. This should match the team that owns this code in the [CODEOWNERS](https://github.com/elastic/kibana/blob/master/.github/CODEOWNERS) file (however, this is not currently enforced). Internal teams should also use a [GitHub team alias](https://github.com/orgs/elastic/teams) for `owner.githubTeam`. While many teams can contribute to a plugin, only a single team should be the primary owner.
+
+`description` - [Required] Give your plugin a description to help other developers understand what it does. This is required for internal plugins.
 
-[3], [4]: Any plugin that you have a dependency on should be listed in `requiredPlugins` or `optionalPlugins`. Doing this will ensure that you have access to that plugin's start and setup contract inside your own plugin's start and setup lifecycle methods. If a plugin you optionally depend on is not installed or disabled, it will be undefined if you try to access it. If a plugin you require is not installed or disabled, kibana will fail to build.
+`requiredPlugins` - [Optional] If your plugin requires any other plugins to work, you must list them here by id. If any of the required plugins are disabled or not installed, then your plugin will be disabled.
 
-[5]: Don't worry too much about getting 5 right. The build optimizer will complain if any of these values are incorrect.
+`optionalPlugins` - [Optional] If your plugin has an optional dependency on other plugins, you must list them here by id. If any of the optional plugins are disabled or not installed, your plugin will still load, however that plugin's API contract will be undefined in the second parameter of the setup and start functions.
 
+`requiredBundles` - [Required in certain situations] Don't worry about getting this right. The build optimizer will complain if any of these values are incorrect.
 
 <DocCallOut>
   You don't need to declare a dependency on a plugin if you only wish to access its types.
@@ -233,7 +256,7 @@ With that specified in the plugin manifest, the appropriate interfaces are then
 import type { CoreSetup, CoreStart } from 'kibana/server';
 import type { FoobarPluginSetup, FoobarPluginStart } from '../../foobar/server';
 
-interface DemoSetupPlugins { [1]
+interface DemoSetupPlugins { [1];
   foobar: FoobarPluginSetup;
 }
 
@@ -242,13 +265,13 @@ interface DemoStartPlugins {
 }
 
 export class DemoPlugin {
-  public setup(core: CoreSetup, plugins: DemoSetupPlugins) { [2]
+  public setup(core: CoreSetup, plugins: DemoSetupPlugins) { [2];
     const { foobar } = plugins;
     foobar.getFoo(); // 'foo'
     foobar.getBar(); // throws because getBar does not exist
   }
 
-  public start(core: CoreStart, plugins: DemoStartPlugins) { [3]
+  public start(core: CoreStart, plugins: DemoStartPlugins) { [3];
     const { foobar } = plugins;
     foobar.getFoo(); // throws because getFoo does not exist
     foobar.getBar(); // 'bar'

diff --git a/examples/bfetch_explorer/kibana.json b/examples/bfetch_explorer/kibana.json
@@ -1,7 +1,7 @@
 {
   "id": "bfetchExplorer",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": true,
   "ui": true,
   "requiredPlugins": ["bfetch", "developerExamples"],

diff --git a/examples/dashboard_embeddable_examples/kibana.json b/examples/dashboard_embeddable_examples/kibana.json
@@ -1,10 +1,21 @@
 {
   "id": "dashboardEmbeddableExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": false,
   "ui": true,
-  "requiredPlugins": ["embeddable", "embeddableExamples", "dashboard", "developerExamples", "kibanaReact"],
+  "requiredPlugins": [
+    "embeddable",
+    "embeddableExamples",
+    "dashboard",
+    "developerExamples",
+    "kibanaReact"
+  ],
+  "owner": {
+    "name": "Presentation",
+    "githubTeam": "kibana-presentation"
+  },
+  "description": "Example app that shows how to embed a dashboard in an application",
   "optionalPlugins": [],
   "requiredBundles": ["esUiShared"]
 }
diff --git a/examples/developer_examples/kibana.json b/examples/developer_examples/kibana.json
@@ -1,9 +1,6 @@
 {
   "id": "developerExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
-  "server": false,
-  "ui": true,
-  "requiredPlugins": [],
-  "optionalPlugins": []
+  "version": "0.0.1",
+  "ui": true
 }
diff --git a/examples/embeddable_examples/kibana.json b/examples/embeddable_examples/kibana.json
@@ -1,9 +1,14 @@
 {
   "id": "embeddableExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": true,
   "ui": true,
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example app that shows how to register custom embeddables",
   "requiredPlugins": ["embeddable", "uiActions", "savedObjects", "dashboard"],
   "optionalPlugins": [],
   "extraPublicDirs": ["public/todo", "public/hello_world", "public/todo/todo_ref_embeddable"],

diff --git a/examples/embeddable_explorer/kibana.json b/examples/embeddable_explorer/kibana.json
@@ -1,9 +1,23 @@
 {
   "id": "embeddableExplorer",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": false,
   "ui": true,
-  "requiredPlugins": ["uiActions", "inspector", "embeddable", "embeddableExamples", "developerExamples", "dashboard", "kibanaReact", "savedObjects"],
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example app that relies on registered functionality in the embeddable_examples plugin",
+  "requiredPlugins": [
+    "uiActions",
+    "inspector",
+    "embeddable",
+    "embeddableExamples",
+    "developerExamples",
+    "dashboard",
+    "kibanaReact",
+    "savedObjects"
+  ],
   "optionalPlugins": []
 }
diff --git a/examples/expressions_explorer/kibana.json b/examples/expressions_explorer/kibana.json
@@ -1,7 +1,7 @@
 {
   "id": "expressionsExplorer",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": false,
   "ui": true,
   "requiredPlugins": ["expressions", "inspector", "uiActions", "developerExamples"],

diff --git a/examples/index_pattern_field_editor_example/kibana.json b/examples/index_pattern_field_editor_example/kibana.json
@@ -1,7 +1,7 @@
 {
   "id": "indexPatternFieldEditorExample",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": false,
   "ui": true,
   "requiredPlugins": ["data", "indexPatternFieldEditor", "developerExamples"],

diff --git a/examples/locator_examples/kibana.json b/examples/locator_examples/kibana.json
@@ -1,12 +1,15 @@
 {
   "id": "locatorExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": false,
   "ui": true,
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example app that registers custom URL locators",
   "requiredPlugins": ["share"],
   "optionalPlugins": [],
-  "extraPublicDirs": [
-    "public/locator"
-  ]
+  "extraPublicDirs": ["public/locator"]
 }
diff --git a/examples/locator_explorer/kibana.json b/examples/locator_explorer/kibana.json
@@ -1,9 +1,14 @@
 {
   "id": "locatorExplorer",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": false,
   "ui": true,
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example app that shows how to use custom URL locators",
   "requiredPlugins": ["share", "locatorExamples", "developerExamples"],
   "optionalPlugins": []
 }
diff --git a/examples/preboot_example/kibana.json b/examples/preboot_example/kibana.json
@@ -1,12 +1,12 @@
 {
   "id": "prebootExample",
+  "kibanaVersion": "kibana",
   "owner": {
     "name": "Core",
     "githubTeam": "kibana-core"
   },
   "description": "The example of the `preboot` plugin.",
   "version": "8.0.0",
-  "kibanaVersion": "kibana",
   "configPath": ["prebootExample"],
   "type": "preboot",
   "server": true,

diff --git a/examples/routing_example/kibana.json b/examples/routing_example/kibana.json
@@ -1,9 +1,14 @@
 {
   "id": "routingExample",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
   "server": true,
   "ui": true,
+  "owner": {
+    "name": "Core",
+    "githubTeam": "kibana-core"
+  },
+  "description": "A simple example of how to use core's routing services",
   "requiredPlugins": ["developerExamples"],
   "optionalPlugins": []
 }
diff --git a/examples/screenshot_mode_example/kibana.json b/examples/screenshot_mode_example/kibana.json
@@ -1,9 +1,14 @@
 {
   "id": "screenshotModeExample",
-  "version": "1.0.0",
   "kibanaVersion": "kibana",
+  "version": "1.0.0",
   "server": true,
   "ui": true,
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example plugin of how to use screenshotMode plugin services",
   "requiredPlugins": ["navigation", "screenshotMode", "usageCollection", "developerExamples"],
   "optionalPlugins": []
 }
diff --git a/examples/search_examples/kibana.json b/examples/search_examples/kibana.json
@@ -1,7 +1,12 @@
 {
   "id": "searchExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example plugin of how to use data plugin search services",
   "server": true,
   "ui": true,
   "requiredPlugins": ["navigation", "data", "developerExamples", "kibanaUtils", "share"],

diff --git a/examples/state_containers_examples/kibana.json b/examples/state_containers_examples/kibana.json
@@ -1,7 +1,12 @@
 {
   "id": "stateContainersExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example plugin of how to use kibanaUtils services",
   "server": false,
   "ui": true,
   "requiredPlugins": ["navigation", "data", "developerExamples"],

diff --git a/examples/ui_action_examples/kibana.json b/examples/ui_action_examples/kibana.json
@@ -1,7 +1,12 @@
 {
   "id": "uiActionsExamples",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example plugin of how to register custom uiActions",
   "server": false,
   "ui": true,
   "requiredPlugins": ["uiActions"],

diff --git a/examples/ui_actions_explorer/kibana.json b/examples/ui_actions_explorer/kibana.json
@@ -1,7 +1,12 @@
 {
   "id": "uiActionsExplorer",
-  "version": "0.0.1",
   "kibanaVersion": "kibana",
+  "version": "0.0.1",
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "Example plugin of how to use uiActions plugin services",
   "server": false,
   "ui": true,
   "requiredPlugins": ["uiActions", "uiActionsExamples", "developerExamples"],