mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 10:40:07 -04:00
Initialize ops documentation section (#132262)
Co-authored-by: Jonathan Budzenski <jon@elastic.co> Co-authored-by: Tiago Costa <tiago.costa@elastic.co>
This commit is contained in:
Spencer
GitHub
parent
0ffb36568b
commit
a10a4f9f03
30 changed files with 485 additions and 131 deletions
15
dev_docs/operations/ci_stats.mdx
Normal file
15
dev_docs/operations/ci_stats.mdx
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
id: kibDevDocsOpsCiStats
|
||||
slug: /kibana-dev-docs/ops/ci-stats
|
||||
title: "Kibana CI Stats"
|
||||
description: A service that we run to track little bits of data about CI runs.
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'ci']
|
||||
---
|
||||
|
||||
Kibana CI Stats (sometimes written "ci-stats") is a service run at https://ci-stats.kibana.dev. This service runs a series of APIs in front of an Elasticsearch Cluster which allows us to record data about each run of CI. This data includes metrics, times, test results, and more. We are working on storing performance data in there too, and eventually will spend time to write good UIs on top of this data.
|
||||
|
||||
The service implementation is available at https://github.com/elastic/kibana-ci-stats/ (private because there doesn't seem to be a good reason to make it public).
|
||||
|
||||
The service is run on Google Cloud Run, which allows us to build a container, push it to GCR, define a memory limit, vCPU count, and concurrent request limit per container, and Google will automatically scale the container for us. It works pretty well and hides a lot of the complexity of running the service. The repo uses Buildkite CI to build and deploy the container when pushing to the main branch. All changes to the main branch must come from PRs, but at this time we don't require review for PRs.
|
||||
|
||||
The website at https://ci-stats.kibana.dev uses EUI and Elastic Charts, and currently has users powered by Github OAuth. When someone authenticates with ci-stats they are first redirected to Github for authentication, then their membership in the Elastic org is checked. Users in the Elastic org will be able to do things that other users can't, like [trigger flaky test runner jobs](https://ci-stats.kibana.dev/trigger_flaky_test_runner).
|
||||
47
dev_docs/operations/operations_landing.mdx
Normal file
47
dev_docs/operations/operations_landing.mdx
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
id: kibDevDocsOpsOverview
|
||||
slug: /kibana-dev-docs/ops
|
||||
title: Kibana Operations
|
||||
description: Links to all the documentation maintained by the Kibana Operations team
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations']
|
||||
layout: landing
|
||||
---
|
||||
|
||||
<DocLandingHero
|
||||
title='Welcome to the ops docs!'
|
||||
description="👋 Here you will find documentation about all the things the Kibana Operations team manages. Feel free to look around and ask questions!"
|
||||
/>
|
||||
|
||||
<DocRelatedArticles
|
||||
sectionTitle='CI'
|
||||
items={[
|
||||
{ pageId: "kibDevDocsOpsCiStats" },
|
||||
]}
|
||||
/>
|
||||
|
||||
<DocRelatedArticles
|
||||
sectionTitle='Build tooling'
|
||||
items={[
|
||||
{ pageId: "kibDevDocsOpsOptimizer" },
|
||||
{ pageId: "kibDevDocsOpsBabelPreset" },
|
||||
{ pageId: "kibDevDocsOpsTypeSummarizer" },
|
||||
]}
|
||||
/>
|
||||
|
||||
<DocRelatedArticles
|
||||
sectionTitle='Linting & Validation'
|
||||
items={[
|
||||
{ pageId: "kibDevDocsOpsEslintConfig" },
|
||||
{ pageId: "kibDevDocsOpsEslintWithTypes" },
|
||||
{ pageId: "kibDevDocsOpsEslintPluginImports" },
|
||||
]}
|
||||
/>
|
||||
|
||||
<DocRelatedArticles
|
||||
sectionTitle='Utilities'
|
||||
items={[
|
||||
{ pageId: "kibDevDocsToolingLog" },
|
||||
{ pageId: "kibDevDocsOpsJestSerializers"},
|
||||
{ pageId: "kibDevDocsOpsExpect" },
|
||||
]}
|
||||
/>
|
||||
|
|
@ -165,6 +165,43 @@
|
|||
{ "id": "kibVisTypeTimeseriesPluginApi" },
|
||||
{ "id": "kibVisualizationsPluginApi" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Operations",
|
||||
"items": [
|
||||
{ "id": "kibDevDocsOpsOverview", "label": "Overview" },
|
||||
{
|
||||
"label": "CI",
|
||||
"items": [
|
||||
{ "id": "kibDevDocsOpsCiStats" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Build tooling",
|
||||
"items": [
|
||||
{ "id": "kibDevDocsOpsOptimizer" },
|
||||
{ "id": "kibDevDocsOpsBabelPreset" },
|
||||
{ "id": "kibDevDocsOpsTypeSummarizer" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Linting & Validation",
|
||||
"items": [
|
||||
{ "id": "kibDevDocsOpsEslintConfig" },
|
||||
{ "id": "kibDevDocsOpsEslintPluginEslint" },
|
||||
{ "id": "kibDevDocsOpsEslintWithTypes" },
|
||||
{ "id": "kibDevDocsOpsEslintPluginImports" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"label": "Utilities",
|
||||
"items": [
|
||||
{ "id": "kibDevDocsToolingLog" },
|
||||
{ "id": "kibDevDocsOpsJestSerializers"},
|
||||
{ "id": "kibDevDocsOpsExpect" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -22,7 +22,6 @@ filegroup(
|
|||
|
||||
NPM_MODULE_EXTRA_FILES = [
|
||||
"package.json",
|
||||
"README.md",
|
||||
]
|
||||
|
||||
RUNTIME_DEPS = [
|
||||
|
|
|
|||
|
|
@ -1,21 +0,0 @@
|
|||
# @kbn/babel-preset
|
||||
|
||||
This package contains the shared bits of babel config that we use for transpiling our source code to code compatible with Node.JS and the various [browsers we support](https://www.elastic.co/support/matrix#matrix_browsers).
|
||||
|
||||
## usage
|
||||
|
||||
To use our presets add the following to the devDependencies section of your package.json:
|
||||
|
||||
```
|
||||
"@kbn/babel-preset": "1.0.0",
|
||||
```
|
||||
|
||||
Then run `yarn kbn bootstrap` to properly link the package into your plugin/package.
|
||||
|
||||
Finally, add either `@kbn/babel-preset/node_preset` or `@kbn/babel-preset/webpack_preset` to your babel config.
|
||||
|
||||
`@kbn/babel-preset/node_preset` is usually placed in a [`babel.config.js` file](https://babeljs.io/docs/en/configuration#babelconfigjs).
|
||||
|
||||
`@kbn/babel-preset/webpack_preset` is usually placed directly in your `webpack` configuration.
|
||||
|
||||
***NOTE:*** If you're transpiling code that will be run in both the browser and node you must transpile your code twice, once for each target. Take a look at the build tasks for `@kbn/i18n` to see how that can look.
|
||||
23
packages/kbn-babel-preset/README.mdx
Normal file
23
packages/kbn-babel-preset/README.mdx
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
id: kibDevDocsOpsBabelPreset
|
||||
slug: /kibana-dev-docs/ops/babel-preset
|
||||
title: "@kbn/babel-preset"
|
||||
description: A package holding the main babel configs on Kibana
|
||||
date: 2022-05-17
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'babel', 'custom', 'preset']
|
||||
---
|
||||
|
||||
This package contains the shared bits of babel config that we use for transpiling our source code to code compatible with Node.JS and the various [browsers we support](https://www.elastic.co/support/matrix#matrix_browsers).
|
||||
|
||||
## Usage
|
||||
|
||||
To use those presets add either `@kbn/babel-preset/node_preset` or `@kbn/babel-preset/webpack_preset` into the babel config file.
|
||||
|
||||
`@kbn/babel-preset/node_preset` is usually placed in a [`babel.config.js` file](https://babeljs.io/docs/en/configuration#babelconfigjs).
|
||||
|
||||
`@kbn/babel-preset/webpack_preset` is usually placed directly in a `webpack` configuration.
|
||||
|
||||
If you're transpiling code that will be run in both the browser and node you must transpile your code twice, once for each target.
|
||||
|
||||
Along with the introduction of Bazel to build packages we also provide now an easier way to easily use the babel transpiler by using the `js_ts_tarnspiler` rule with our without the `web` property enabled.
|
||||
Take a look for example at `@kbn/i18n` to see how that can look.
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
# elastic-eslint-config-kibana
|
||||
|
||||
The eslint config used by the kibana team
|
||||
|
||||
## Usage
|
||||
|
||||
To use this eslint config, just install the peer dependencies and reference it
|
||||
in your `.eslintrc`:
|
||||
|
||||
```javascript
|
||||
{
|
||||
extends: [
|
||||
'@kbn/eslint-config'
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Optional jest config
|
||||
|
||||
If the project uses the [jest test runner](https://facebook.github.io/jest/),
|
||||
the `@kbn/eslint-config/jest` config can be extended as well to use
|
||||
`eslint-plugin-jest` and add settings specific to it:
|
||||
|
||||
```javascript
|
||||
{
|
||||
extends: [
|
||||
'@kbn/eslint-config',
|
||||
'@kbn/eslint-config/jest'
|
||||
]
|
||||
}
|
||||
```
|
||||
39
packages/kbn-eslint-config/README.mdx
Normal file
39
packages/kbn-eslint-config/README.mdx
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
id: kibDevDocsOpsEslintConfig
|
||||
slug: /kibana-dev-docs/ops/eslint-config
|
||||
title: "@kbn/eslint-config"
|
||||
description: A package holding the main eslint configs on Kibana
|
||||
date: 2022-05-16
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'eslint', 'custom', 'config']
|
||||
---
|
||||
|
||||
This package is used to group and provide the eslint configurations used by the Kibana team.
|
||||
It defines default plugins, env, parserOptions and rules for javascript, typescript, and react code bases.
|
||||
Optionally it can also be used with jest as explained below.
|
||||
|
||||
## Usage
|
||||
|
||||
To use this eslint config, it needs to be referenced in the `.eslintrc` file:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
extends: [
|
||||
'@kbn/eslint-config'
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Optional jest eslint config
|
||||
|
||||
If [jest test runner](https://facebook.github.io/jest/) is used,
|
||||
the `@kbn/eslint-config/jest` config can be extended as well to use
|
||||
`eslint-plugin-jest` and add settings specific to it:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
extends: [
|
||||
'@kbn/eslint-config',
|
||||
'@kbn/eslint-config/jest'
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -26,7 +26,6 @@ filegroup(
|
|||
|
||||
NPM_MODULE_EXTRA_FILES = [
|
||||
"package.json",
|
||||
"README.md",
|
||||
]
|
||||
|
||||
RUNTIME_DEPS = [
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
# Custom ESLint rules for Kibana
|
||||
|
||||
This package contains custom ESLint rules used for Kibana development.
|
||||
147
packages/kbn-eslint-plugin-eslint/README.mdx
Normal file
147
packages/kbn-eslint-plugin-eslint/README.mdx
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
id: kibDevDocsOpsEslintPluginEslint
|
||||
slug: /kibana-dev-docs/ops/eslint-plugin-eslint
|
||||
title: "@kbn/eslint-plugin-eslint"
|
||||
description: A package holding an eslint plugin with custom rules used on Kibana
|
||||
date: 2022-05-17
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'eslint', 'plugin']
|
||||
---
|
||||
|
||||
An ESLint plugin exposing custom rules used and built specifically for development within Kibana.
|
||||
Next you can find information on each on.
|
||||
|
||||
## disallow-license-headers
|
||||
|
||||
Disallows a given group of license header texts on a group of files.
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
overrides: [
|
||||
{
|
||||
files: ['**/*.{js,mjs,ts,tsx}'],
|
||||
rules: {
|
||||
'@kbn/eslint/disallow-license-headers': [
|
||||
'error',
|
||||
{
|
||||
licenses: [
|
||||
"LICENSE_TEXT"
|
||||
],
|
||||
},
|
||||
],
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## module_migration
|
||||
|
||||
Offers a way to force a migration from a given node module into another as an alternative.
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
overrides: [
|
||||
{
|
||||
files: ['**/*.{js,mjs,ts,tsx}'],
|
||||
rules: {
|
||||
'@kbn/eslint/module_migration': [
|
||||
'error',
|
||||
[
|
||||
{
|
||||
from: 'expect.js',
|
||||
to: '@kbn/expect',
|
||||
}
|
||||
],
|
||||
],
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## no_async_foreach
|
||||
|
||||
Disallows passing an async function to .forEach which will avoid promise rejections from being handled. asyncForEach() or a similar helper from "@kbn/std" should be used instead.
|
||||
|
||||
## no_async_promise_body
|
||||
|
||||
Disallows the usage of an async function as a constructor for a Promise function without a try catch in place.
|
||||
|
||||
## no_constructor_args_in_property_initializers
|
||||
|
||||
Disallows the usage of constructor arguments into class property initializers.
|
||||
|
||||
## no_export_all
|
||||
|
||||
Disables the usage of `export *`.
|
||||
|
||||
## no_this_in_property_initializers
|
||||
|
||||
Disallows the usage of `this` into class property initializers and enforce to define the property value into the constructor.
|
||||
|
||||
## no_trailing_import_slash
|
||||
|
||||
Disables the usage of a trailing slash in a node module import.
|
||||
|
||||
## no-restricted-paths
|
||||
|
||||
Defines a set of import paths valid to be imported for a given group of files.
|
||||
|
||||
```
|
||||
module.exports = {
|
||||
overrides: [
|
||||
{
|
||||
files: ['**/*.{js,mjs,ts,tsx}'],
|
||||
rules: {
|
||||
'@kbn/eslint/no-restricted-paths': [
|
||||
'error',
|
||||
{
|
||||
basePath: __dirname,
|
||||
zones: [
|
||||
{
|
||||
target: [
|
||||
'(src|x-pack)/plugins/**/(public|server)/**/*',
|
||||
'examples/**/*',
|
||||
'!(src|x-pack)/**/*.test.*',
|
||||
'!(x-pack/)?test/**/*',
|
||||
],
|
||||
from: [
|
||||
'(src|x-pack)/plugins/**/(public|server)/**/*',
|
||||
'!(src|x-pack)/plugins/**/(public|server)/mocks/index.{js,mjs,ts}',
|
||||
'!(src|x-pack)/plugins/**/(public|server)/(index|mocks).{js,mjs,ts,tsx}',
|
||||
'!(src|x-pack)/plugins/**/__stories__/index.{js,mjs,ts,tsx}',
|
||||
'!(src|x-pack)/plugins/**/__fixtures__/index.{js,mjs,ts,tsx}',
|
||||
],
|
||||
allowSameFolder: true,
|
||||
errorMessage: 'Plugins may only import from top-level public and server modules.',
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## require-license-header
|
||||
|
||||
Requires a given license header text on a group of files.
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
overrides: [
|
||||
{
|
||||
files: ['**/*.{js,mjs,ts,tsx}'],
|
||||
rules: {
|
||||
'@kbn/eslint/require-license-header': [
|
||||
'error',
|
||||
{
|
||||
license: "LICENSE_TEXT"
|
||||
},
|
||||
],
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -28,7 +28,7 @@ function isTsParameterProperty(param) {
|
|||
* @param {string} arg
|
||||
*/
|
||||
const errorMsg = (arg) =>
|
||||
`The constructor argument "${arg}" can't be used in a class property intializer, define the property in the constructor instead`;
|
||||
`The constructor argument "${arg}" can't be used in a class property initializer, define the property in the constructor instead`;
|
||||
|
||||
/** @type {Rule} */
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ ruleTester.run('@kbn/eslint/no_constructor_args_in_property_initializers', rule,
|
|||
errors: [
|
||||
{
|
||||
line: 2,
|
||||
message: `The constructor argument "foo" can't be used in a class property intializer, define the property in the constructor instead`,
|
||||
message: `The constructor argument "foo" can't be used in a class property initializer, define the property in the constructor instead`,
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
@ -77,7 +77,7 @@ ruleTester.run('@kbn/eslint/no_constructor_args_in_property_initializers', rule,
|
|||
errors: [
|
||||
{
|
||||
line: 2,
|
||||
message: `The constructor argument "foo" can't be used in a class property intializer, define the property in the constructor instead`,
|
||||
message: `The constructor argument "foo" can't be used in a class property initializer, define the property in the constructor instead`,
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
@ -91,7 +91,7 @@ ruleTester.run('@kbn/eslint/no_constructor_args_in_property_initializers', rule,
|
|||
errors: [
|
||||
{
|
||||
line: 2,
|
||||
message: `The constructor argument "foo" can't be used in a class property intializer, define the property in the constructor instead`,
|
||||
message: `The constructor argument "foo" can't be used in a class property initializer, define the property in the constructor instead`,
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
@ -111,7 +111,7 @@ ruleTester.run('@kbn/eslint/no_constructor_args_in_property_initializers', rule,
|
|||
errors: [
|
||||
{
|
||||
line: 2,
|
||||
message: `The constructor argument "deps" can't be used in a class property intializer, define the property in the constructor instead`,
|
||||
message: `The constructor argument "deps" can't be used in a class property initializer, define the property in the constructor instead`,
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ const esTypes = tsEstree.AST_NODE_TYPES;
|
|||
/**
|
||||
* @param {string} arg
|
||||
*/
|
||||
const ERROR_MSG = `"this" is not fully initialized in class property intializers, define the value for this property in the constructor instead`;
|
||||
const ERROR_MSG = `"this" is not fully initialized in class property initializers, define the value for this property in the constructor instead`;
|
||||
|
||||
/** @type {Rule} */
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -71,7 +71,7 @@ ruleTester.run('@kbn/eslint/no_this_in_property_initializers', rule, {
|
|||
errors: [
|
||||
{
|
||||
line: 2,
|
||||
message: `"this" is not fully initialized in class property intializers, define the value for this property in the constructor instead`,
|
||||
message: `"this" is not fully initialized in class property initializers, define the value for this property in the constructor instead`,
|
||||
},
|
||||
],
|
||||
},
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
/** @typedef {import("@typescript-eslint/typescript-estree").TSESTree.ImportDeclaration} ImportDeclaration */
|
||||
|
||||
const ERROR_MSG =
|
||||
'Using a trailing slash in package import statements causes issues with webpack and is inconsistent with the rest of the respository.';
|
||||
'Using a trailing slash in package import statements causes issues with webpack and is inconsistent with the rest of the repository.';
|
||||
|
||||
/** @type {Rule} */
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ ruleTester.run('@kbn/eslint/no_trailing_import_slash', rule, {
|
|||
{
|
||||
line: 1,
|
||||
message:
|
||||
'Using a trailing slash in package import statements causes issues with webpack and is inconsistent with the rest of the respository.',
|
||||
'Using a trailing slash in package import statements causes issues with webpack and is inconsistent with the rest of the repository.',
|
||||
},
|
||||
],
|
||||
output: dedent`
|
||||
|
|
@ -64,7 +64,7 @@ ruleTester.run('@kbn/eslint/no_trailing_import_slash', rule, {
|
|||
{
|
||||
line: 1,
|
||||
message:
|
||||
'Using a trailing slash in package import statements causes issues with webpack and is inconsistent with the rest of the respository.',
|
||||
'Using a trailing slash in package import statements causes issues with webpack and is inconsistent with the rest of the repository.',
|
||||
},
|
||||
],
|
||||
output: dedent`
|
||||
|
|
|
|||
|
|
@ -1,6 +1,12 @@
|
|||
# @kbn/eslint-plugin-imports
|
||||
---
|
||||
id: kibDevDocsOpsEslintPluginImports
|
||||
slug: /kibana-dev-docs/ops/kbn-eslint-plugin-imports
|
||||
title: "@kbn/eslint-plugin-imports"
|
||||
description: Custom ESLint rules for managing `imports` in the Kibana repository
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'eslint', 'imports']
|
||||
---
|
||||
|
||||
ESLint plugin providing custom rules for validating imports in the Kibana repo with custom logic beyond what's possible with custom config to eslint-plugin-imports and even a custom resolver.
|
||||
`@kbn/eslint-plugin-imports` is an ESLint plugin providing custom rules for validating imports in the Kibana repo with custom logic beyond what's possible with custom config to eslint-plugin-imports and even a custom resolver.
|
||||
|
||||
For the purposes of this ESLint plugin "imports" include:
|
||||
|
||||
|
|
@ -19,7 +19,6 @@ filegroup(
|
|||
NPM_MODULE_EXTRA_FILES = [
|
||||
"LICENSE.txt",
|
||||
"package.json",
|
||||
"README.md",
|
||||
]
|
||||
|
||||
js_library(
|
||||
|
|
|
|||
|
|
@ -1,6 +1,11 @@
|
|||
> NOTE: This is a local fork of https://github.com/Automattic/expect.js
|
||||
|
||||
# @kbn/expect
|
||||
---
|
||||
id: kibDevDocsOpsExpect
|
||||
slug: /kibana-dev-docs/ops/expect
|
||||
title: "@kbn/expect"
|
||||
description: An assertion toolkit based on should.js
|
||||
date: 2022-05-17
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'expect']
|
||||
---
|
||||
|
||||
Minimalistic BDD assertion toolkit based on
|
||||
[should.js](http://github.com/visionmedia/should.js)
|
||||
|
|
@ -13,6 +18,8 @@ expect([]).to.be.an('array');
|
|||
expect(window).not.to.be.an(Image);
|
||||
```
|
||||
|
||||
> NOTE: This is a local fork of https://github.com/Automattic/expect.js
|
||||
|
||||
## Features
|
||||
|
||||
- Cross-browser: works on IE6+, Firefox, Safari, Chrome, Opera.
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
# @kbn/jest-serializers
|
||||
|
||||
Shared serializers that may be useful when you're writing jest tests. To use them import the package and call one of the functions, passing the result to `expect.addSnapshotSerializer()`.
|
||||
|
||||
Example:
|
||||
|
||||
```ts
|
||||
import { createAbsolutePathSerializer } from '@kbn/jest-serializers'
|
||||
|
||||
expect.addSnapshotSerializer(createAbsolutePathSerializer());
|
||||
```
|
||||
38
packages/kbn-jest-serializers/README.mdx
Normal file
38
packages/kbn-jest-serializers/README.mdx
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
id: kibDevDocsOpsJestSerializers
|
||||
slug: /kibana-dev-docs/ops/jest-serializers
|
||||
title: "@kbn/jest-serializers"
|
||||
description: A set of shared serializers to help on writing jest tests
|
||||
date: 2022-05-17
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'jest', 'serializers']
|
||||
---
|
||||
|
||||
This package holds a set of shared serializers that may be useful when you're writing jest tests. To use them import the package and call one of the functions, passing the result to `expect.addSnapshotSerializer()`.
|
||||
|
||||
## createAbsolutePathSerializer
|
||||
|
||||
Replaces a given path starting a string with the provided replacer. Additionally also replaces any `\\` with `/` it founds.
|
||||
|
||||
## createStripAnsiSerializer
|
||||
|
||||
Strips ansi from a string.
|
||||
|
||||
## createRecursiveSerializer
|
||||
|
||||
It helps on printing recursive nodes.
|
||||
|
||||
## createAnyInstanceSerializer
|
||||
|
||||
It serializes any kind of instance inside `<>`. If it is a function calls the function inside the node otherwise prints as `Class.name`.
|
||||
|
||||
## createReplaceSerializer
|
||||
|
||||
Search for a substring using given Regex or string and replaces with a provided replacer.
|
||||
|
||||
## Example
|
||||
|
||||
```ts
|
||||
import { createAbsolutePathSerializer } from '@kbn/jest-serializers'
|
||||
|
||||
expect.addSnapshotSerializer(createAbsolutePathSerializer());
|
||||
```
|
||||
|
|
@ -27,7 +27,6 @@ NPM_MODULE_EXTRA_FILES = [
|
|||
"limits.yml",
|
||||
"package.json",
|
||||
"postcss.config.js",
|
||||
"README.md"
|
||||
]
|
||||
|
||||
RUNTIME_DEPS = [
|
||||
|
|
|
|||
|
|
@ -1,4 +1,11 @@
|
|||
# @kbn/optimizer
|
||||
---
|
||||
id: kibDevDocsOpsOptimizer
|
||||
slug: /kibana-dev-docs/ops/optimizer
|
||||
title: "@kbn/optimizer"
|
||||
description: 'The tool which builds front-end bundles for plugins.'
|
||||
date: 2022-05-16
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'optimizer', 'webpack']
|
||||
---
|
||||
|
||||
`@kbn/optimizer` is a package for building Kibana platform UI plugins (and hopefully more soon).
|
||||
|
||||
|
|
@ -61,7 +68,7 @@ KBN_OPTIMIZER_THEMES=* yarn start
|
|||
|
||||
## API
|
||||
|
||||
To run the optimizer from code, you can import the [`OptimizerConfig`][OptimizerConfig] class and [`runOptimizer`][Optimizer] function. Create an [`OptimizerConfig`][OptimizerConfig] instance by calling it's static `create()` method with some options, then pass it to the [`runOptimizer`][Optimizer] function. `runOptimizer()` returns an observable of update objects, which are summaries of the optimizer state plus an optional `event` property which describes the internal events occuring and may be of use. You can use the [`logOptimizerState()`][LogOptimizerState] helper to write the relevant bits of state to a tooling log or checkout it's implementation to see how the internal events like [`WorkerStdio`][ObserveWorker] and [`WorkerStarted`][ObserveWorker] are used.
|
||||
To run the optimizer from code, you can import the [`OptimizerConfig`][OptimizerConfig] class and [`runOptimizer`][runOptimizer] function. Create an [`OptimizerConfig`][OptimizerConfig] instance by calling it's static `create()` method with some options, then pass it to the [`runOptimizer`][runOptimizer] function. `runOptimizer()` returns an observable of update objects, which are summaries of the optimizer state plus an optional `event` property which describes the internal events occuring and may be of use. You can use the [`logOptimizerState()`][LogOptimizerState] helper to write the relevant bits of state to a tooling log or checkout it's implementation to see how the internal events like [`WorkerStdio`][ObserveWorker] and [`WorkerStarted`][ObserveWorker] are used.
|
||||
|
||||
Example:
|
||||
```ts
|
||||
|
|
@ -125,16 +132,15 @@ Workers have several error message they may emit which indicate unrecoverable er
|
|||
For an example of how to handle these states checkout the [`logOptimizerState()`][LogOptimizerState] helper.
|
||||
|
||||
[PostCss]: https://postcss.org/
|
||||
[Cli]: src/cli.ts
|
||||
[Optimizer]: src/optimizer.ts
|
||||
[ObserveWorker]: src/observe_worker.ts
|
||||
[CompilerMsg]: src/common/compiler_messages.ts
|
||||
[WorkerMsg]: src/common/worker_messages.ts
|
||||
[Bundle]: src/common/bundle.ts
|
||||
[WebpackConfig]: src/worker/webpack.config.ts
|
||||
[BundleDefinition]: src/common/bundle_definition.ts
|
||||
[WorkerConfig]: src/common/worker_config.ts
|
||||
[OptimizerConfig]: src/optimizer_config.ts
|
||||
[LogOptimizerState]: src/log_optimizer_state.ts
|
||||
[AssignBundlesToWorkers]: src/assign_bundles_to_workers.ts
|
||||
[BuildTask]: ../../src/dev/build/tasks/build_kibana_platform_plugins.js
|
||||
[Cli]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/cli.ts
|
||||
[runOptimizer]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/run_optimizer.ts
|
||||
[ObserveWorker]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/optimizer/observe_worker.ts
|
||||
[CompilerMsg]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/common/compiler_messages.ts
|
||||
[WorkerMsg]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/common/worker_messages.ts
|
||||
[Bundle]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/common/bundle.ts
|
||||
[WebpackConfig]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/worker/webpack.config.ts
|
||||
[WorkerConfig]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/common/worker_config.ts
|
||||
[OptimizerConfig]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/optimizer/optimizer_config.ts
|
||||
[LogOptimizerState]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/log_optimizer_state.ts
|
||||
[AssignBundlesToWorkers]: https://github.com/elastic/kibana/blob/main/packages/kbn-optimizer/src/optimizer/assign_bundles_to_workers.ts
|
||||
[BuildTask]: https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/build_kibana_platform_plugins.js
|
||||
|
|
@ -1,3 +0,0 @@
|
|||
# @kbn/tooling-log
|
||||
|
||||
Empty package generated by @kbn/generate
|
||||
24
packages/kbn-tooling-log/README.mdx
Normal file
24
packages/kbn-tooling-log/README.mdx
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
id: kibDevDocsToolingLog
|
||||
slug: /kibana-dev-docs/tooling-log
|
||||
title: "@kbn/tooling-log"
|
||||
description: Standard logger used by lots of tooling in the Kibana repository.
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'logging']
|
||||
---
|
||||
|
||||
The Kibana ToolingLog is a basic logger used by just about all tooling in the Kibana respository that gives us a single indented logging interface to manage.
|
||||
|
||||
In the Functional Test Runner, or in the vast majority of CLIs/scripts, a log instance is created for you and should be reused so that the level/output/indent level are synced across uses.
|
||||
|
||||
To get the `ToolingLog` instance in the Functional Test Runner use `getService('log')`.
|
||||
|
||||
To get the `ToolingLog` instance in CLIs, it's passed to the function at the root of the CLI:
|
||||
```ts
|
||||
import { run } from '@kbn/dev-utils'
|
||||
run(async ({ flags, log }) => {
|
||||
log.info('hello')
|
||||
await ...
|
||||
});
|
||||
```
|
||||
|
||||
API Reference: <DocLink id="kibKbnToolingLogPluginApi" />
|
||||
|
|
@ -20,7 +20,6 @@ filegroup(
|
|||
|
||||
NPM_MODULE_EXTRA_FILES = [
|
||||
"package.json",
|
||||
"README.md",
|
||||
]
|
||||
|
||||
RUNTIME_DEPS = [
|
||||
|
|
|
|||
|
|
@ -1,6 +1,13 @@
|
|||
# @kbn/type-summarizer
|
||||
---
|
||||
id: kibDevDocsOpsTypeSummarizer
|
||||
slug: /kibana-dev-docs/ops/type-summarizer
|
||||
title: "@kbn/type-summarizer (BETA)"
|
||||
description: A tool to summarize and produce a single .d.ts file from tsc output supporting sourcemaps
|
||||
date: 2022-05-17
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'type', 'summarizer', 'typescript', 'bundler', 'sourcemap']
|
||||
---
|
||||
|
||||
Consume the .d.ts files for a package, produced by `tsc`, and generate a single `.d.ts` file of the public types along with a source map that points back to the original source.
|
||||
Consumes the .d.ts files for a package, produced by `tsc`, and generates a single `.d.ts` file of the public types along with a source map that points back to the original source.
|
||||
|
||||
## You mean like API Extractor?
|
||||
|
||||
|
|
@ -14,4 +21,4 @@ The plan is to expand to other packages in the Kibana repo, adding support for l
|
|||
|
||||
## Something isn't working and I'm blocked!
|
||||
|
||||
If there's a problem with the implmentation blocking another team at any point we can move the package back to using api-extractor by removing the package from the `TYPE_SUMMARIZER_PACKAGES` list at the top of [packages/kbn-type-summarizer/src/lib/bazel_cli_config.ts](./src/lib/bazel_cli_config.ts).
|
||||
If there's a problem with the implementation blocking another team at any point we can move the package back to using api-extractor by removing the package from the `TYPE_SUMMARIZER_PACKAGES` list at the top of [packages/kbn-type-summarizer/src/lib/bazel_cli_config.ts](https://github.com/elastic/kibana/blob/main/packages/kbn-type-summarizer/src/lib/bazel_cli_config.ts).
|
||||
|
|
@ -1,11 +1,14 @@
|
|||
# dev/build
|
||||
---
|
||||
id: kibDevDocsOpsBuildSystem
|
||||
slug: /kibana-dev-docs/ops/build-system
|
||||
title: "Build System"
|
||||
description: Build the Kibana distributable
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'build']
|
||||
---
|
||||
|
||||
Build the default and OSS distributables of Kibana.
|
||||
|
||||
# Quick Start
|
||||
|
||||
```sh
|
||||
## Quick Start
|
||||
|
||||
```shell
|
||||
# checkout the help for this script
|
||||
node scripts/build --help
|
||||
|
||||
|
|
@ -16,36 +19,34 @@ node scripts/build --release
|
|||
node scripts/build --skip-node-download --debug
|
||||
```
|
||||
|
||||
# Fixing out of memory issues
|
||||
## Fixing out of memory issues
|
||||
|
||||
Building Kibana and its distributables can take a lot of memory to finish successfully. Builds do make use of child processes, which means you can increase the amount of memory available by specifying `NODE_OPTIONS="--max-old-space-size=VALUE-IN-MEGABYTES"`.
|
||||
|
||||
```sh
|
||||
|
||||
```shell
|
||||
# Use 4GB instead of the standard 1GB for building
|
||||
NODE_OPTIONS="--max-old-space-size=4096" node scripts/build --release
|
||||
```
|
||||
|
||||
# Structure
|
||||
## Structure
|
||||
|
||||
The majority of this logic is extracted from the legacy grunt build, and is designed to maintain the general structure grunt provides including tasks and config. The [build_distributables.js] file defines which tasks are run.
|
||||
The majority of this logic is extracted from the legacy grunt build, and is designed to maintain the general structure grunt provides including tasks and config. The [build_distributables.ts] file defines which tasks are run.
|
||||
|
||||
**Task**: [tasks/\*] define individual parts of the build. Each task is an object with a `run()` method, a `description` property, and optionally a `global` property. They are executed with the runner either once (if they are global) or once for each build. Non-global/local tasks are called once for each build, meaning they will be called twice be default, once for the OSS build and once for the default build and receive a build object as the third argument to `run()` which can be used to determine paths and properties for that build.
|
||||
**Task**: [tasks/\*] define individual parts of the build. Each task is an object with a `run()` method, a `description` property, and optionally a `global` property. They are executed with the runner either once (if they are global) or once for each build. Non-global/local tasks are called once for each build and receive a build object as the third argument to `run()` which can be used to determine paths and properties for that build.
|
||||
|
||||
**Config**: [lib/config.js] defines the config used to execute tasks. It is mostly used to determine absolute paths to specific locations, and to get access to the Platforms.
|
||||
**Config**: [lib/config.ts] defines the config used to execute tasks. It is mostly used to determine absolute paths to specific locations, and to get access to the Platforms.
|
||||
|
||||
**Platform**: [lib/platform.js] defines the Platform objects, which define the different platforms we build for. Use `config.getTargetPlatforms()` to get the list of platforms we are targeting in this build, `config.getNodePlatforms()` to get the list of platform we will download node for, or `config.getPlatform` to get a specific platform and architecture.
|
||||
**Platform**: [lib/platform.ts] defines the Platform objects, which define the different platforms we build for. Use `config.getTargetPlatforms()` to get the list of platforms we are targeting in this build, `config.getNodePlatforms()` to get the list of platform we will download node for, or `config.getPlatform` to get a specific platform and architecture.
|
||||
|
||||
**Log**: We use the `ToolingLog` defined in [@kbn/tooling-log]
|
||||
**Log**: We use the `ToolingLog` defined in <DocLink id="kibDevDocsToolingLog" />
|
||||
|
||||
**Runner**: [lib/runner.js] defines the runner used to execute tasks. It calls tasks with specific arguments based on whether they are global or not.
|
||||
**Runner**: [lib/runner.ts] defines the runner used to execute tasks. It calls tasks with specific arguments based on whether they are global or not.
|
||||
|
||||
**Build**: [lib/build.js], created by the runner and passed to tasks so they can resolve paths and get information about the build they are operating on.
|
||||
**Build**: [lib/build.ts], created by the runner and passed to tasks so they can resolve paths and get information about the build they are operating on.
|
||||
|
||||
[tasks/\*]: ./tasks
|
||||
[lib/config.js]: ./lib/config.js
|
||||
[lib/platform.js]: ./lib/platform.js
|
||||
[lib/runner.js]: ./lib/runner.js
|
||||
[lib/build.js]: ./lib/build.js
|
||||
[build_distributables.js]: ./build_distributables.js
|
||||
[@kbn/tooling-log]: ../../../packages/kbn-tooling-log
|
||||
[tasks/\*]: https://github.com/elastic/kibana/tree/main/src/dev/build/tasks
|
||||
[lib/config.ts]: https://github.com/elastic/kibana/blob/main/src/dev/build/lib/config.ts
|
||||
[lib/platform.ts]: https://github.com/elastic/kibana/blob/main/src/dev/build/lib/platform.ts
|
||||
[lib/runner.ts]: https://github.com/elastic/kibana/blob/main/src/dev/build/lib/runner.ts
|
||||
[lib/build.ts]: https://github.com/elastic/kibana/blob/main/src/dev/build/lib/build.ts
|
||||
[build_distributables.ts]: https://github.com/elastic/kibana/blob/main/src/dev/build/build_distributables.ts
|
||||
31
src/dev/eslint/eslint_with_types.mdx
Normal file
31
src/dev/eslint/eslint_with_types.mdx
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
id: kibDevDocsOpsEslintWithTypes
|
||||
slug: /kibana-dev-docs/ops/eslint-with-types
|
||||
title: "ESLint (with types)"
|
||||
description: Running ESLint in a way that enabled advanced rules which consume the TypeScript type checker
|
||||
tags: ['kibana', 'dev', 'contributor', 'operations', 'eslint', 'ts']
|
||||
---
|
||||
|
||||
By default ESLint works on a single file, parses that files to an abtract-syntax-tree (AST), and then writes validations against the syntax in that one file. This prevents us from using fancy rules which validate code based on the types of a specific variable, or anything along those lines. Running ESLint *with types* loads a specific TypeScript project into the ESLint context and uses it to include properties of the types to inform specific validations.
|
||||
|
||||
The only rule we have enabled so far is `@typescript-eslint/consistent-type-exports` [[docs](https://typescript-eslint.io/rules/consistent-type-exports/)].
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
node scripts/eslint_with_types --help
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
Because ESLint needs to load up the TypeScript project into memory this script can only lint the code for one TypeScript project at a time. To take advantage of modern CPUs and introduce parallelsim to ESLint we run a number of ESLint processes in parallel, each loading a different TypeScript project into memory and then exitting, allowing a new worker to be spawned.
|
||||
|
||||
To tell ESLint which project to load, we actually generate an ESLint config file which points to the right tsconfig.json file and includes the rules we are going to validate for that project.
|
||||
|
||||
## Parallel ESLint?!
|
||||
|
||||
Yep! If you've ever tried to run ESLint on the whole project you know that it takes approximately 40 years. It's actually one of the slowest parts single parts of CI. We are aiming to make ESLint (with types) the default linter soon, deprecating or removing the global ESLint config.
|
||||
|
||||
## How do I customize the rules for my plugin?
|
||||
|
||||
We don't support that yet and are trying to come up with a way that supports some amount of customizability without support for 200+ unique configurations for ESLint based on which directory you're in an thousands of `// eslint-disable-next-line`s all over the repo because rules are incorrectly managed.
|
||||
Loading…
Add table
Add a link
Reference in a new issue