Merge branch 'master' into lens/unmount-bug

.eslintrc.js

@@ -89,6 +89,72 @@ const SAFER_LODASH_SET_DEFINITELYTYPED_HEADER = `
  */
 `;
 
+/** Packages which should not be included within production code. */
+const DEV_PACKAGES = [
+  'kbn-babel-code-parser',
+  'kbn-dev-utils',
+  'kbn-docs-utils',
+  'kbn-es*',
+  'kbn-eslint*',
+  'kbn-optimizer',
+  'kbn-plugin-generator',
+  'kbn-plugin-helpers',
+  'kbn-pm',
+  'kbn-storybook',
+  'kbn-telemetry-tools',
+  'kbn-test',
+];
+
+/** Directories (at any depth) which include dev-only code. */
+const DEV_DIRECTORIES = [
+  '.storybook',
+  '__tests__',
+  '__test__',
+  '__jest__',
+  '__fixtures__',
+  '__mocks__',
+  '__stories__',
+  'e2e',
+  'fixtures',
+  'ftr_e2e',
+  'integration_tests',
+  'manual_tests',
+  'mock',
+  'storybook',
+  'scripts',
+  'test',
+  'test-d',
+  'test_utils',
+  'test_utilities',
+  'test_helpers',
+  'tests_client_integration',
+];
+
+/** File patterns for dev-only code. */
+const DEV_FILE_PATTERNS = [
+  '*.mock.{js,ts,tsx}',
+  '*.test.{js,ts,tsx}',
+  '*.test.helpers.{js,ts,tsx}',
+  '*.stories.{js,ts,tsx}',
+  '*.story.{js,ts,tsx}',
+  '*.stub.{js,ts,tsx}',
+  'mock.{js,ts,tsx}',
+  '_stubs.{js,ts,tsx}',
+  '{testHelpers,test_helper,test_utils}.{js,ts,tsx}',
+  '{postcss,webpack}.config.js',
+];
+
+/** Glob patterns which describe dev-only code. */
+const DEV_PATTERNS = [
+  ...DEV_PACKAGES.map((pkg) => `packages/${pkg}/**/*`),
+  ...DEV_DIRECTORIES.map((dir) => `{packages,src,x-pack}/**/${dir}/**/*`),
+  ...DEV_FILE_PATTERNS.map((file) => `{packages,src,x-pack}/**/${file}`),
+  'packages/kbn-interpreter/tasks/**/*',
+  'src/dev/**/*',
+  'x-pack/{dev-tools,tasks,scripts,test,build_chromium}/**/*',
+  'x-pack/plugins/*/server/scripts/**/*',
+];
+
 module.exports = {
   root: true,
 
@@ -491,43 +557,17 @@ module.exports = {
     },
 
     /**
-     * Files that ARE NOT allowed to use devDependencies
-     */
-    {
-      files: ['x-pack/**/*.js', 'packages/kbn-interpreter/**/*.js'],
-      rules: {
-        'import/no-extraneous-dependencies': [
-          'error',
-          {
-            devDependencies: false,
-            peerDependencies: true,
-            packageDir: '.',
-          },
-        ],
-      },
-    },
-
-    /**
-     * Files that ARE allowed to use devDependencies
+     * Single package.json rules, it tells eslint to ignore the child package.json files
+     * and look for dependencies declarations in the single and root level package.json
      */
     {
-      files: [
-        'packages/kbn-es/src/**/*.js',
-        'packages/kbn-interpreter/tasks/**/*.js',
-        'packages/kbn-interpreter/src/plugin/**/*.js',
-        'x-pack/{dev-tools,tasks,scripts,test,build_chromium}/**/*.js',
-        'x-pack/**/{__tests__,__test__,__jest__,__fixtures__,__mocks__,public}/**/*.js',
-        'x-pack/**/*.test.js',
-        'x-pack/test_utils/**/*',
-        'x-pack/gulpfile.js',
-        'x-pack/plugins/apm/public/utils/testHelpers.js',
-        'x-pack/plugins/canvas/shareable_runtime/postcss.config.js',
-      ],
+      files: ['{src,x-pack,packages}/**/*.{js,mjs,ts,tsx}'],
       rules: {
         'import/no-extraneous-dependencies': [
           'error',
           {
-            devDependencies: true,
+            /* Files that ARE allowed to use devDependencies */
+            devDependencies: [...DEV_PATTERNS],
             peerDependencies: true,
             packageDir: '.',
           },
@@ -1420,21 +1460,5 @@ module.exports = {
         ],
       },
     },
-
-    /**
-     * Single package.json rules, it tells eslint to ignore the child package.json files
-     * and look for dependencies declarations in the single and root level package.json
-     */
-    {
-      files: ['**/*.{js,mjs,ts,tsx}'],
-      rules: {
-        'import/no-extraneous-dependencies': [
-          'error',
-          {
-            packageDir: '.',
-          },
-        ],
-      },
-    },
   ],
 };

.github/CODEOWNERS

@@ -59,6 +59,7 @@
 /x-pack/plugins/embeddable_enhanced/ @elastic/kibana-app-services
 /x-pack/plugins/ui_actions_enhanced/ @elastic/kibana-app-services
 /x-pack/plugins/runtime_fields @elastic/kibana-app-services
+/x-pack/test/search_sessions_integration/ @elastic/kibana-app-services
 #CC# /src/plugins/bfetch/ @elastic/kibana-app-services
 #CC# /src/plugins/index_pattern_management/ @elastic/kibana-app-services
 #CC# /src/plugins/inspector/ @elastic/kibana-app-services

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question
+    url: https://discuss.elastic.co/c/kibana
+    about: Please ask and answer questions here.

dev_docs/best_practices.mdx

@@ -12,6 +12,132 @@ tags: ['kibana', 'onboarding', 'dev', 'architecture']
 First things first, be sure to review our <DocLink id="kibDevPrinciples" text="development principles"/> and check out all the available
 platform <DocLink id="kibBuildingBlocks" text="building blocks"/> that can simplify plugin development.
 
+## Developer documentation
+
+### High-level documentation
+
+#### Structure
+
+Refer to [divio documentation](https://documentation.divio.com/) for guidance on where and how to structure our high-level documentation.
+
+<DocLink id="kibDevDocsWelcome" text="Getting started" /> and
+<DocLink id="kibPlatformIntro" text="Key concepts" /> sections are both _explanation_ oriented,
+<DocLink id="kibDevTutorialBuildAPlugin" text="Tutorials" /> covers both _tutorials_ and _How to_, and
+the <DocLink id="kibDevDocsApiWelcome" text="API documentation" /> section covers _reference_ material.
+
+#### Location
+
+If the information spans multiple plugins, consider adding it to the [dev_docs](https://github.com/elastic/kibana/tree/master/dev_docs) folder. If it is plugin specific, consider adding it inside the plugin folder. Write it in an mdx file if you would like it to show up in our new (beta) documentation system.
+
+<DocCallOut title="internal only">
+
+To add docs into the new docs system, create an `.mdx` file that
+contains <DocLink id="docsSyntax" section="frontmatter" text="frontmatter"/>. Read about the syntax <DocLink id="docsSyntax" text="here"/>. An extra step is needed to add a menu item. <DocLink id="docsSetup" text="These instructions" /> will walk you through how to set the docs system
+up locally and edit the nav menu.
+
+</DocCallOut>
+
+#### Keep content fresh
+
+A fresh pair of eyes are invaluable. Recruit new hires to read, review and update documentation. Leads should also periodically review documentation to ensure it stays up to date. File issues any time you notice documentation is outdated.
+
+#### Consider your target audience
+
+Documentation in the Kibana Developer Guide is targeted towards developers building Kibana plugins. Keep implementation details about internal plugin code out of these docs.
+
+#### High to low level
+
+When a developer first lands in our docs, think about their journey. Introduce basic concepts before diving into details. The left navigation should be set up so documents on top are higher level than documents near the bottom.
+
+#### Think outside-in
+
+It's easy to forget what it felt like to first write code in Kibana, but do your best to frame these docs "outside-in". Don't use esoteric, internal language unless a definition is documented and linked. The fresh eyes of a new hire can be a great asset.
+
+### API documentation
+
+We automatically generate <DocLink id="kibDevDocsApiWelcome" text="API documentation"/>. The following guidelines will help ensure your <DocLink id="kibPlatformIntro" section="public-plugin-api" text="public APIs" /> are useful.
+
+#### Code comments
+
+Every publicly exposed function, class, interface, type, parameter and property should have a comment using JSDoc style comments.
+
+- Use `@param` tags for every function parameter.
+- Use `@returns` tags for return types.
+- Use `@throws` when appropriate.
+- Use `@beta` or `@deprecated` when appropriate.
+- Use `@internal` to indicate this API item is intended for internal use only, which will also remove it from the docs.
+
+#### Interfaces vs inlined types
+
+Prefer types and interfaces over complex inline objects. For example, prefer:
+
+```ts
+/**
+* The SearchSpec interface contains settings for creating a new SearchService, like
+* username and password.
+*/
+export interface SearchSpec {
+ /**
+  * Stores the username. Duh,
+  */
+ username: string;
+ /**
+  * Stores the password. I hope it's encrypted!
+  */
+ password: string;
+}
+
+ /**
+  * Retrieve search services
+  * @param searchSpec Configuration information for initializing the search service.
+  * @returns the id of the search service
+  */
+export getSearchService: (searchSpec: SearchSpec) => string;
+```
+
+over:
+
+```ts
+/**
+  * Retrieve search services
+  * @param searchSpec Configuration information for initializing the search service.
+  * @returns the id of the search service
+  */
+export getSearchService: (searchSpec: { username: string; password: string }) => string;
+```
+
+In the former, there will be a link to the `SearchSpec` interface with documentation for the `username` and `password` properties. In the latter the object will render inline, without comments:
+
+![prefer interfaces documentation](./assets/dev_docs_nested_object.png)
+
+#### Export every type used in a public API
+
+When a publicly exported API items references a private type, this results in a broken link in our docs system. The private type is, by proxy, part of your public API, and as such, should be exported.
+
+Do:
+
+```ts
+export interface AnInterface { bar: string };
+export type foo: string | AnInterface;
+```
+
+Don't:
+
+```ts
+interface AnInterface { bar: string };
+export type foo: string | AnInterface;
+```
+
+#### Avoid “Pick”
+
+`Pick` not only ends up being unhelpful in our documentation system, but it's also of limited help in your IDE. For that reason, avoid `Pick` and other similarly complex types on your public API items. Using these semantics internally is fine.
+
+![pick api documentation](./assets/api_doc_pick.png)
+
+### Example plugins
+
+Running Kibana with `yarn start --run-examples` will include all [example plugins](https://github.com/elastic/kibana/tree/master/examples). These are tested examples of platform services in use. We strongly encourage anyone providing a platform level service or <DocLink id="kibBuildingBlocks" text="building block"/> to include a tutorial that links to a tested example plugin. This is better than relying on copied code snippets, which can quickly get out of date.
+
 ## Performance
 
 Build with scalability in mind.

docs/api/actions-and-connectors.asciidoc

@@ -5,19 +5,19 @@ Manage Actions and Connectors.
 
 The following connector APIs are available:
 
-* <<actions-and-connectors-api-get, Get connector API>> to retrieve a single connector by ID
+* <<get-connector-api, Get connector API>> to retrieve a single connector by ID
 
-* <<actions-and-connectors-api-get-all, Get all connectors API>> to retrieve all connectors
+* <<get-all-connectors-api, Get all connectors API>> to retrieve all connectors
 
-* <<actions-and-connectors-api-list, List all connector types API>> to retrieve a list of all connector types
+* <<list-connector-types-api, List all connector types API>> to retrieve a list of all connector types
 
-* <<actions-and-connectors-api-create, Create connector API>> to create connectors
+* <<create-connector-api, Create connector API>> to create connectors
 
-* <<actions-and-connectors-api-update, Update connector API>> to update the attributes for an existing connector
+* <<update-connector-api, Update connector API>> to update the attributes for an existing connector
 
-* <<actions-and-connectors-api-execute, Execute connector API>> to execute a connector by ID
+* <<execute-connector-api, Execute connector API>> to execute a connector by ID
 
-* <<actions-and-connectors-api-delete, Delete connector API>> to delete a connector by ID
+* <<delete-connector-api, Delete connector API>> to delete a connector by ID
 
 For deprecated APIs, refer to <<actions-and-connectors-legacy-apis>>.
 

docs/api/actions-and-connectors/create.asciidoc

@@ -1,25 +1,25 @@
-[[actions-and-connectors-api-create]]
+[[create-connector-api]]
 === Create connector API
 ++++
-<titleabbrev>Create connector API</titleabbrev>
+<titleabbrev>Create connector</titleabbrev>
 ++++
 
 Creates a connector.
 
-[[actions-and-connectors-api-create-request]]
+[[create-connector-api-request]]
 ==== Request
 
 `POST <kibana host>:<port>/api/actions/connector`
 
 `POST <kibana host>:<port>/s/<space_id>/api/actions/connector`
 
-[[actions-and-connectors-api-create-path-params]]
+[[create-connector-api-path-params]]
 ==== Path parameters
 
 `space_id`::
   (Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
 
-[[actions-and-connectors-api-create-request-body]]
+[[create-connector-api-request-body]]
 ==== Request body
 
 `name`::
@@ -36,15 +36,15 @@ Creates a connector.
   (Required, object) The secrets configuration for the connector. Secrets configuration properties vary
   depending on the connector type. For information about the secrets configuration properties, refer to <<action-types,Action and connector types>>.
 +
-WARNING: Remember these values. You must provide them each time you call the <<actions-and-connectors-api-update, update>> API.
+WARNING: Remember these values. You must provide them each time you call the <<update-connector-api, update>> API.
 
-[[actions-and-connectors-api-create-request-codes]]
+[[create-connector-api-request-codes]]
 ==== Response code
 
 `200`::
     Indicates a successful call.
 
-[[actions-and-connectors-api-create-example]]
+[[create-connector-api-example]]
 ==== Example
 
 [source,sh]