diff --git a/docs/developer/advanced/development-basepath.asciidoc b/docs/developer/advanced/development-basepath.asciidoc index f0b760a21ea0c..cb341b9591174 100644 --- a/docs/developer/advanced/development-basepath.asciidoc +++ b/docs/developer/advanced/development-basepath.asciidoc @@ -1,5 +1,5 @@ [[development-basepath]] -=== Considerations for basepath +== Considerations for basepath In dev mode, {kib} by default runs behind a proxy which adds a random path component to its URL. diff --git a/docs/developer/advanced/development-es-snapshots.asciidoc b/docs/developer/advanced/development-es-snapshots.asciidoc index 92fae7a241edf..4c801bf750979 100644 --- a/docs/developer/advanced/development-es-snapshots.asciidoc +++ b/docs/developer/advanced/development-es-snapshots.asciidoc @@ -1,32 +1,32 @@ [[development-es-snapshots]] -=== Daily Elasticsearch Snapshots +== Daily {es} Snapshots -For local development and CI, {kib}, by default, uses Elasticsearch snapshots that are built daily when running tasks that require Elasticsearch (e.g. functional tests). +For local development and CI, {kib}, by default, uses {es} snapshots that are built daily when running tasks that require {es} (e.g. functional tests). -A snapshot is just a group of tarballs, one for each supported distribution/architecture/os of Elasticsearch, and a JSON-based manifest file containing metadata about the distributions. +A snapshot is just a group of tarballs, one for each supported distribution/architecture/os of {es}, and a JSON-based manifest file containing metadata about the distributions. -https://ci.kibana.dev/es-snapshots[A dashboard] is available that shows the current status and compatibility of the latest Elasticsearch snapshots. +https://ci.kibana.dev/es-snapshots[A dashboard] is available that shows the current status and compatibility of the latest {es} snapshots. -==== Process Overview +=== Process Overview -1. Elasticsearch snapshots are built for each current tracked branch of {kib}. +1. {es} snapshots are built for each current tracked branch of {kib}. 2. Each snapshot is uploaded to a public Google Cloud Storage bucket, `kibana-ci-es-snapshots-daily`. ** At this point, the snapshot is not automatically used in CI or local development. It needs to be tested/verified first. 3. Each snapshot is tested with the latest commit of the corresponding {kib} branch, using the full CI suite. 4. After CI ** If the snapshot passes, it is promoted and automatically used in CI and local development. -** If the snapshot fails, the issue must be investigated and resolved. A new incompatibility may exist between Elasticsearch and {kib}. +** If the snapshot fails, the issue must be investigated and resolved. A new incompatibility may exist between {es} and {kib}. -==== Using the latest snapshot +=== Using the latest snapshot -When developing locally, you may wish to use the most recent Elasticsearch snapshot, even if it's failing CI. To do so, prefix your commands with the follow environment variable: +When developing locally, you may wish to use the most recent {es} snapshot, even if it's failing CI. To do so, prefix your commands with the follow environment variable: ["source","bash"] ----------- KBN_ES_SNAPSHOT_USE_UNVERIFIED=true ----------- -You can use this flag with any command that downloads and runs Elasticsearch snapshots, such as `scripts/es` or the FTR. +You can use this flag with any command that downloads and runs {es} snapshots, such as `scripts/es` or the FTR. For example, to run functional tests with the latest snapshot: @@ -35,7 +35,7 @@ For example, to run functional tests with the latest snapshot: KBN_ES_SNAPSHOT_USE_UNVERIFIED=true node scripts/functional_tests_server ----------- -===== For Pull Requests +==== For Pull Requests Currently, there is not a way to run your pull request with the latest unverified snapshot without a code change. You can, however, do it with a small code change. @@ -45,9 +45,9 @@ Currently, there is not a way to run your pull request with the latest unverifie Your pull request should then use the latest snapshot the next time that it runs. Just don't merge the change to `Jenkinsfile`! -==== Google Cloud Storage buckets +=== Google Cloud Storage buckets -===== kibana-ci-es-snapshots-daily +==== kibana-ci-es-snapshots-daily This bucket stores snapshots that are created on a daily basis, and is the primary location used by `kbn-es` to download snapshots. @@ -61,7 +61,7 @@ The file structure for this bucket looks like this: * `/archives//*.tar.gz.sha512` * `/archives//manifest.json` -===== kibana-ci-es-snapshots-permanent +==== kibana-ci-es-snapshots-permanent This bucket stores only the most recently promoted snapshot for each version. Old snapshots are only deleted when new ones are uploaded. @@ -73,18 +73,18 @@ The file structure for this bucket looks like this: * `/*.tar.gz.sha512` * `/manifest.json` -==== How snapshots are built, tested, and promoted +=== How snapshots are built, tested, and promoted -Each day, a https://kibana-ci.elastic.co/job/elasticsearch+snapshots+trigger/[Jenkins job] runs that triggers Elasticsearch builds for each currently tracked branch/version. This job is automatically updated with the correct branches whenever we release new versions of {kib}. +Each day, a https://kibana-ci.elastic.co/job/elasticsearch+snapshots+trigger/[Jenkins job] runs that triggers {es} builds for each currently tracked branch/version. This job is automatically updated with the correct branches whenever we release new versions of {kib}. -===== Build +==== Build -https://kibana-ci.elastic.co/job/elasticsearch+snapshots+build/[This Jenkins job] builds the Elasticsearch snapshots and uploads them to GCS. +https://kibana-ci.elastic.co/job/elasticsearch+snapshots+build/[This Jenkins job] builds the {es} snapshots and uploads them to GCS. The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/master/.ci/es-snapshots/Jenkinsfile_build_es[in the {kib} repo]. -1. Checkout Elasticsearch repo for the given branch/version. -2. Run `./gradlew -p distribution/archives assemble --parallel` to create all of the Elasticsearch distributions. +1. Checkout {es} repo for the given branch/version. +2. Run `./gradlew -p distribution/archives assemble --parallel` to create all of the {es} distributions. 3. Create a tarball for each distribution. 4. Create a manifest JSON file containing info about the distribution, as well as its download URL. 5. Upload the tarballs and manifest to a unique location in the GCS bucket `kibana-ci-es-snapshots-daily`. @@ -93,9 +93,9 @@ The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/ma ** This allows the `KBN_ES_SNAPSHOT_USE_UNVERIFIED` flag to work. 7. Trigger the verification job, to run the full {kib} CI test suite with this snapshot. -===== Verification and Promotion +==== Verification and Promotion -https://kibana-ci.elastic.co/job/elasticsearch+snapshots+verify/[This Jenkins job] tests the latest Elasticsearch snapshot with the full {kib} CI pipeline, and promotes if it there are no test failures. +https://kibana-ci.elastic.co/job/elasticsearch+snapshots+verify/[This Jenkins job] tests the latest {es} snapshot with the full {kib} CI pipeline, and promotes if it there are no test failures. The Jenkins job pipeline definition is https://github.com/elastic/kibana/blob/master/.ci/es-snapshots/Jenkinsfile_verify_es[in the {kib} repo]. diff --git a/docs/developer/advanced/index.asciidoc b/docs/developer/advanced/index.asciidoc index 139940ee42fe2..5c53bedd95e72 100644 --- a/docs/developer/advanced/index.asciidoc +++ b/docs/developer/advanced/index.asciidoc @@ -5,8 +5,8 @@ * <> * <> -include::development-es-snapshots.asciidoc[] +include::development-es-snapshots.asciidoc[leveloffset=+1] -include::running-elasticsearch.asciidoc[] +include::running-elasticsearch.asciidoc[leveloffset=+1] -include::development-basepath.asciidoc[] \ No newline at end of file +include::development-basepath.asciidoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/developer/advanced/running-elasticsearch.asciidoc b/docs/developer/advanced/running-elasticsearch.asciidoc index b03c231678eee..2361f805c7635 100644 --- a/docs/developer/advanced/running-elasticsearch.asciidoc +++ b/docs/developer/advanced/running-elasticsearch.asciidoc @@ -1,13 +1,13 @@ [[running-elasticsearch]] -=== Running elasticsearch during development +== Running {es} during development -There are many ways to run Elasticsearch while you are developing. +There are many ways to run {es} while you are developing. -[float] +[discrete] -==== By snapshot +=== By snapshot -This will run a snapshot of elasticsearch that is usually built nightly. Read more about <>. +This will run a snapshot of {es} that is usually built nightly. Read more about <>. [source,bash] ---- @@ -25,36 +25,36 @@ yarn es snapshot --help **Keeping data between snapshots** -If you want to keep the data inside your Elasticsearch between usages of this command, you should use the following command, to keep your data folder outside the downloaded snapshot folder: +If you want to keep the data inside your {es} between usages of this command, you should use the following command, to keep your data folder outside the downloaded snapshot folder: [source,bash] ---- yarn es snapshot -E path.data=../data ---- -==== By source +=== By source -If you have the Elasticsearch repo checked out locally and wish to run against that, use `source`. By default, it will reference an elasticsearch checkout which is a sibling to the {kib} directory named elasticsearch. If you wish to use a checkout in another location you can provide that by supplying --source-path +If you have the {es} repo checked out locally and wish to run against that, use `source`. By default, it will reference an {es} checkout which is a sibling to the {kib} directory named elasticsearch. If you wish to use a checkout in another location you can provide that by supplying --source-path [source,bash] ---- yarn es source ---- -==== From an archive +=== From an archive -Use this if you already have a distributable. For released versions, one can be obtained on the Elasticsearch downloads page. +Use this if you already have a distributable. For released versions, one can be obtained on the {es} downloads page. [source,bash] ---- yarn es archive ---- -Each of these will run Elasticsearch with a basic license. Additional options are available, pass --help for more information. +Each of these will run {es} with a basic license. Additional options are available, pass --help for more information. -==== From a remote host +=== From a remote host -You can save some system resources, and the effort of generating sample data, if you have a remote Elasticsearch cluster to connect to. (Elasticians: you do! Check with your team about where to find credentials) +You can save some system resources, and the effort of generating sample data, if you have a remote {es} cluster to connect to. (Elasticians: you do! Check with your team about where to find credentials) You'll need to create a kibana.dev.yml (<>) and add the following to it: @@ -75,7 +75,7 @@ kibana.index: '.{YourGitHubHandle}-kibana' xpack.task_manager.index: '.{YourGitHubHandle}-task-manager-kibana' ---- -===== Running remote clusters +==== Running remote clusters Setup remote clusters for cross cluster search (CCS) and cross cluster replication (CCR). @@ -95,7 +95,7 @@ yarn es snapshot -E transport.port=9500 -E http.port=9201 -E path.data=../data_p Once both clusters are running, start {kib}. {kib} will connect to the primary cluster. -Setup the remote cluster in {kib} from either Management -> Elasticsearch -> Remote Clusters UI or by running the following script in Console. +Setup the remote cluster in {kib} from either Management -> {es} -> Remote Clusters UI or by running the following script in Console. [source,bash] ---- diff --git a/docs/developer/architecture/add-data-tutorials.asciidoc b/docs/developer/architecture/add-data-tutorials.asciidoc index e16b1bc039a10..3891b87a00e64 100644 --- a/docs/developer/architecture/add-data-tutorials.asciidoc +++ b/docs/developer/architecture/add-data-tutorials.asciidoc @@ -1,16 +1,16 @@ [[add-data-tutorials]] -=== Add data tutorials +== Add data tutorials `Add Data` in the {kib} Home application contains tutorials for setting up data flows in the Elastic stack. Each tutorial contains three sets of instructions: -* `On Premise.` Set up a data flow when both {kib} and Elasticsearch are running on premise. -* `On Premise Elastic Cloud.` Set up a data flow when {kib} is running on premise and Elasticsearch is running on Elastic Cloud. -* `Elastic Cloud.` Set up a data flow when both {kib} and Elasticsearch are running on Elastic Cloud. +* `On Premise.` Set up a data flow when both {kib} and {es} are running on premise. +* `On Premise Elastic Cloud.` Set up a data flow when {kib} is running on premise and {es} is running on Elastic Cloud. +* `Elastic Cloud.` Set up a data flow when both {kib} and {es} are running on Elastic Cloud. -[float] -==== Creating a new tutorial +[discrete] +=== Creating a new tutorial 1. Create a new directory in the link:https://github.com/elastic/kibana/tree/master/src/plugins/home/server/tutorials[tutorials directory]. 2. In the new directory, create a file called `index.ts` that exports a function. The function must return a function object that conforms to the `TutorialSchema` interface link:{kib-repo}tree/{branch}/src/plugins/home/server/services/tutorials/lib/tutorial_schema.ts[tutorial schema]. @@ -23,15 +23,15 @@ The function must return a function object that conforms to the `TutorialSchema` If you are creating a new plugin and the tutorial is only related to that plugin, you can also place the `TutorialSchema` object into your plugin folder. Add `home` to the `requiredPlugins` list in your `kibana.json` file. Then register the tutorial object by calling `home.tutorials.registerTutorial(tutorialObject)` in the `setup` lifecycle of your server plugin. -[float] -===== Variables +[discrete] +==== Variables String values can contain variables that are substituted when rendered. Variables are specified by `{}`. For example: `{config.docs.version}` is rendered as `6.2` when running the tutorial in {kib} 6.2. link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/np_ready/components/tutorial/replace_template_strings.js#L23[Provided variables] -[float] -===== Markdown +[discrete] +==== Markdown String values can contain limited Markdown syntax. link:{kib-repo}tree/{branch}/src/legacy/core_plugins/kibana/public/home/components/tutorial/content.js#L8[Enabled Markdown grammars] diff --git a/docs/developer/architecture/development-visualize-index.asciidoc b/docs/developer/architecture/development-visualize-index.asciidoc index 551c41833fb72..d41ee32c1fb27 100644 --- a/docs/developer/architecture/development-visualize-index.asciidoc +++ b/docs/developer/architecture/development-visualize-index.asciidoc @@ -1,5 +1,5 @@ [[development-visualize-index]] -=== Developing Visualizations +== Developing Visualizations [IMPORTANT] ============================================== diff --git a/docs/developer/architecture/index.asciidoc b/docs/developer/architecture/index.asciidoc index c3f1658755e9f..2ae19ec73e2ff 100644 --- a/docs/developer/architecture/index.asciidoc +++ b/docs/developer/architecture/index.asciidoc @@ -19,10 +19,10 @@ A few notable services are called out below. * <> * <> -include::add-data-tutorials.asciidoc[] +include::add-data-tutorials.asciidoc[leveloffset=+1] -include::development-visualize-index.asciidoc[] +include::development-visualize-index.asciidoc[leveloffset=+1] -include::security/index.asciidoc[] +include::security/index.asciidoc[leveloffset=+1] -include::code-exploration.asciidoc[] \ No newline at end of file +include::code-exploration.asciidoc[] diff --git a/docs/developer/architecture/security/feature-registration.asciidoc b/docs/developer/architecture/security/feature-registration.asciidoc index 164f6d1cf9c74..3724624dbb917 100644 --- a/docs/developer/architecture/security/feature-registration.asciidoc +++ b/docs/developer/architecture/security/feature-registration.asciidoc @@ -1,13 +1,13 @@ [[development-plugin-feature-registration]] -==== Plugin feature registration +== Plugin feature registration If your plugin will be used with {kib}'s default distribution, then you have the ability to register the features that your plugin provides. Features are typically apps in {kib}; once registered, you can toggle them via Spaces, and secure them via Roles when security is enabled. -===== UI Capabilities +=== UI Capabilities Registering features also gives your plugin access to “UI Capabilities”. These capabilities are boolean flags that you can use to conditionally render your interface, based on the current user's permissions. For example, you can hide or disable a Save button if the current user is not authorized. -===== Registering a feature +=== Registering a feature Feature registration is controlled via the built-in `xpack_main` plugin. To register a feature, call `xpack_main`'s `registerFeature` function from your plugin's `init` function, and provide the appropriate details: @@ -21,7 +21,7 @@ init(server) { } ----------- -===== Feature details +=== Feature details Registering a feature consists of the following fields. For more information, consult the {kib-repo}blob/{branch}/x-pack/plugins/features/server/feature_registry.ts[feature registry interface]. @@ -65,12 +65,12 @@ Registering a feature consists of the following fields. For more information, co |The ID of the navigation link associated with your feature. |=== -====== Privilege definition +==== Privilege definition The `privileges` section of feature registration allows plugins to implement read/write and read-only modes for their applications. For a full explanation of fields and options, consult the {kib-repo}blob/{branch}/x-pack/plugins/features/server/feature_registry.ts[feature registry interface]. -===== Using UI Capabilities +=== Using UI Capabilities UI Capabilities are available to your public (client) plugin code. These capabilities are read-only, and are used to inform the UI. This object is namespaced by feature id. For example, if your feature id is “foo”, then your UI Capabilities are stored at `uiCapabilities.foo`. To access capabilities, import them from `ui/capabilities`: @@ -86,7 +86,7 @@ if (canUserSave) { ----------- [[example-1-canvas]] -===== Example 1: Canvas Application +=== Example 1: Canvas Application ["source","javascript"] ----------- init(server) { @@ -141,7 +141,7 @@ if (canUserSave) { Because the `read` privilege does not define the `save` capability, users with read-only access will have their `uiCapabilities.canvas.save` flag set to `false`. [[example-2-dev-tools]] -===== Example 2: Dev Tools +=== Example 2: Dev Tools ["source","javascript"] ----------- @@ -176,7 +176,7 @@ init(server) { }, privilegesTooltip: i18n.translate('xpack.features.devToolsPrivilegesTooltip', { defaultMessage: - 'User should also be granted the appropriate Elasticsearch cluster and index privileges', + 'User should also be granted the appropriate {es} cluster and index privileges', }), }); } @@ -199,7 +199,7 @@ server.route({ ----------- [[example-3-discover]] -===== Example 3: Discover +=== Example 3: Discover Discover takes advantage of subfeature privileges to allow fine-grained access control. In this example, a single "Create Short URLs" subfeature privilege is defined, which allows users to grant access to this feature without having to grant the `all` privilege to Discover. In other words, you can grant `read` access to Discover, and also grant the ability to create short URLs. diff --git a/docs/developer/architecture/security/index.asciidoc b/docs/developer/architecture/security/index.asciidoc index 802c6634ec741..b7a9d8fa9eee1 100644 --- a/docs/developer/architecture/security/index.asciidoc +++ b/docs/developer/architecture/security/index.asciidoc @@ -1,12 +1,14 @@ [[development-security]] -=== Security +== Security -{kib} has generally been able to implement security transparently to core and plugin developers, and this largely remains the case. {kib} on two methods that the elasticsearch `Cluster` provides: `callWithRequest` and `callWithInternalUser`. +{kib} has generally been able to implement security transparently to core and plugin developers, and this largely remains the case. {kib} on two methods that the {es} `Cluster` provides: `callWithRequest` and `callWithInternalUser`. -`callWithRequest` executes requests against Elasticsearch using the authentication credentials of the {kib} end-user. So, if you log into {kib} with the user of `foo` when `callWithRequest` is used, {kib} execute the request against Elasticsearch as the user `foo`. Historically, `callWithRequest` has been used extensively to perform actions that are initiated at the request of {kib} end-users. +`callWithRequest` executes requests against {es} using the authentication credentials of the {kib} end-user. So, if you log into {kib} with the user of `foo` when `callWithRequest` is used, {kib} execute the request against {es} as the user `foo`. Historically, `callWithRequest` has been used extensively to perform actions that are initiated at the request of {kib} end-users. -`callWithInternalUser` executes requests against Elasticsearch using the internal {kib} server user, and has historically been used for performing actions that aren't initiated by {kib} end users; for example, creating the initial `.kibana` index or performing health checks against Elasticsearch. +`callWithInternalUser` executes requests against {es} using the internal {kib} server user, and has historically been used for performing actions that aren't initiated by {kib} end users; for example, creating the initial `.kibana` index or performing health checks against {es}. -However, with the changes that role-based access control (RBAC) introduces, this is no longer cut and dry. {kib} now requires all access to the `.kibana` index goes through the `SavedObjectsClient`. This used to be a best practice, as the `SavedObjectsClient` was responsible for translating the documents stored in Elasticsearch to and from Saved Objects, but RBAC is now taking advantage of this abstraction to implement access control and determine when to use `callWithRequest` versus `callWithInternalUser`. +However, with the changes that role-based access control (RBAC) introduces, this is no longer cut and dry. {kib} now requires all access to the `.kibana` index goes through the `SavedObjectsClient`. This used to be a best practice, as the `SavedObjectsClient` was responsible for translating the documents stored in {es} to and from Saved Objects, but RBAC is now taking advantage of this abstraction to implement access control and determine when to use `callWithRequest` versus `callWithInternalUser`. -include::rbac.asciidoc[] +include::rbac.asciidoc[leveloffset=+1] + +include::feature-registration.asciidoc[leveloffset=+1] diff --git a/docs/developer/architecture/security/rbac.asciidoc b/docs/developer/architecture/security/rbac.asciidoc index 7fd73cf358884..35f109ad33654 100644 --- a/docs/developer/architecture/security/rbac.asciidoc +++ b/docs/developer/architecture/security/rbac.asciidoc @@ -1,10 +1,10 @@ [discrete] [[development-rbac]] -==== Role-based access control +== Role-based access control Role-based access control (RBAC) in {kib} relies upon the {ref}/security-privileges.html#application-privileges[application privileges] -that Elasticsearch exposes. This allows {kib} to define the privileges that +that {es} exposes. This allows {kib} to define the privileges that {kib} wishes to grant to users, assign them to the relevant users using roles, and then authorize the user to perform a specific action. This is handled within a secured instance of the `SavedObjectsClient` and available transparently to @@ -13,7 +13,7 @@ consumers when using `request.getSavedObjectsClient()` or [discrete] [[development-rbac-privileges]] -===== {kib} Privileges +=== {kib} Privileges When {kib} first starts up, it executes the following `POST` request against {es}. This synchronizes the definition of the privileges with various `actions` which are later used to authorize a user: @@ -59,7 +59,7 @@ The application is created by concatenating the prefix of `kibana-` with the val [discrete] [[development-rbac-assigning-privileges]] -===== Assigning {kib} Privileges +=== Assigning {kib} Privileges {kib} privileges are assigned to specific roles using the `applications` element. For example, the following role assigns the <> privilege at `*` `resources` (which will in the future be used to secure spaces) to the default {kib} `application`: @@ -85,7 +85,7 @@ Roles that grant <> should be managed using the <> * <> -include::stability.asciidoc[] +include::stability.asciidoc[leveloffset=+1] -include::security.asciidoc[] +include::security.asciidoc[leveloffset=+1] diff --git a/docs/developer/best-practices/security.asciidoc b/docs/developer/best-practices/security.asciidoc index 26fcc73ce2b90..79ecb08295064 100644 --- a/docs/developer/best-practices/security.asciidoc +++ b/docs/developer/best-practices/security.asciidoc @@ -1,5 +1,5 @@ [[security-best-practices]] -=== Security best practices +== Security best practices * XSS ** Check for usages of `dangerouslySetInnerHtml`, `Element.innerHTML`, @@ -44,7 +44,7 @@ sensitive information which end up in the HTTP Response ** Ensure no sensitive cookies are forwarded to external resources. ** Ensure that all user controllable variables that are used in constructing a URL are escaped properly. This is relevant when using -`transport.request` with the Elasticsearch client as no automatic +`transport.request` with the {es} client as no automatic escaping is performed. * Reverse tabnabbing - https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/HTML5_Security_Cheat_Sheet.md#tabnabbing diff --git a/docs/developer/best-practices/stability.asciidoc b/docs/developer/best-practices/stability.asciidoc index 68237a034be52..f4b7ae1229909 100644 --- a/docs/developer/best-practices/stability.asciidoc +++ b/docs/developer/best-practices/stability.asciidoc @@ -1,10 +1,10 @@ [[stability]] -=== Stability +== Stability Ensure your feature will work under all possible {kib} scenarios. -[float] -==== Environmental configuration scenarios +[discrete] +=== Environmental configuration scenarios * Cloud ** Does the feature work on *cloud environment*? @@ -32,16 +32,16 @@ non-standard {kib} indices. (create their own custom roles) sessions. (we have had many discuss/SDH tickets around this) * If a proxy/loadbalancer is running between ES and {kib} -[float] -==== Kibana.yml settings +[discrete] +=== Kibana.yml settings * Using a custom {kib} index alias * When optional dependencies are disabled ** Ensure all your required dependencies are listed in kibana.json dependency list! -[float] -==== Test coverage +[discrete] +=== Test coverage * Does the feature have sufficient unit test coverage? (does it handle storeinSessions?) @@ -49,16 +49,16 @@ storeinSessions?) * Does the feature have sufficient Rest API coverage test coverage? * Does the feature have sufficient Integration test coverage? -[float] -==== Browser coverage +[discrete] +=== Browser coverage Refer to the list of browsers and OS {kib} supports https://www.elastic.co/support/matrix Does the feature work efficiently on the list of supported browsers? -[float] -==== Upgrade Scenarios - Migration scenarios- +[discrete] +=== Upgrade Scenarios - Migration scenarios- Does the feature affect old indices, saved objects ? - Has the feature been tested with {kib} diff --git a/docs/developer/contributing/development-accessibility-tests.asciidoc b/docs/developer/contributing/development-accessibility-tests.asciidoc index a3ffefb94cd2a..facf7ff14a6c1 100644 --- a/docs/developer/contributing/development-accessibility-tests.asciidoc +++ b/docs/developer/contributing/development-accessibility-tests.asciidoc @@ -1,5 +1,5 @@ [[development-accessibility-tests]] -==== Automated Accessibility Testing +== Automated Accessibility Testing To run the tests locally: diff --git a/docs/developer/contributing/development-documentation.asciidoc b/docs/developer/contributing/development-documentation.asciidoc index d9fae42eef87e..99e55963f57af 100644 --- a/docs/developer/contributing/development-documentation.asciidoc +++ b/docs/developer/contributing/development-documentation.asciidoc @@ -1,18 +1,18 @@ [[development-documentation]] -=== Documentation during development +== Documentation during development Docs should be written during development and accompany PRs when relevant. There are multiple types of documentation, and different places to add each. -[float] -==== Developer services documentation +[discrete] +=== Developer services documentation Documentation about specific services a plugin offers should be encapsulated in: * README.asciidoc at the base of the plugin folder. * Typescript comments for all public services. -[float] -==== End user documentation +[discrete] +=== End user documentation Documentation about user facing features should be written in http://asciidoc.org/[asciidoc] at {kib-repo}/tree/master/docs[https://github.com/elastic/kibana/tree/master/docs] @@ -27,8 +27,8 @@ README for getting the docs tooling set up. node scripts/docs.js --open ``` -[float] -==== General developer documentation and guidelines +[discrete] +=== General developer documentation and guidelines General developer guildlines and documentation, like this right here, should be written in http://asciidoc.org/[asciidoc] at {kib-repo}/tree/master/docs/developer[https://github.com/elastic/kibana/tree/master/docs/developer] diff --git a/docs/developer/contributing/development-functional-tests.asciidoc b/docs/developer/contributing/development-functional-tests.asciidoc index 7823654c24f61..101de4dfbfbf3 100644 --- a/docs/developer/contributing/development-functional-tests.asciidoc +++ b/docs/developer/contributing/development-functional-tests.asciidoc @@ -1,10 +1,10 @@ [[development-functional-tests]] -=== Functional Testing +== Functional Testing We use functional tests to make sure the {kib} UI works as expected. It replaces hours of manual testing by automating user interaction. To have better control over our functional test environment, and to make it more accessible to plugin authors, {kib} uses a tool called the `FunctionalTestRunner`. -[float] -==== Running functional tests +[discrete] +=== Running functional tests The `FunctionalTestRunner` is very bare bones and gets most of its functionality from its config file, located at {blob}test/functional/config.js[test/functional/config.js]. If you’re writing a plugin outside the {kib} repo, you will have your own config file. See <> for more info. @@ -12,27 +12,27 @@ The `FunctionalTestRunner` is very bare bones and gets most of its functionality There are three ways to run the tests depending on your goals: 1. Easiest option: -** Description: Starts up {kib} & Elasticsearch servers, followed by running tests. This is much slower when running the tests multiple times because slow startup time for the servers. Recommended for single-runs. +** Description: Starts up {kib} & {es} servers, followed by running tests. This is much slower when running the tests multiple times because slow startup time for the servers. Recommended for single-runs. ** `node scripts/functional_tests` -*** does everything in a single command, including running Elasticsearch and {kib} locally +*** does everything in a single command, including running {es} and {kib} locally *** tears down everything after the tests run *** exit code reports success/failure of the tests 2. Best for development: -** Description: Two commands, run in separate terminals, separate the components that are long-running and slow from those that are ephemeral and fast. Tests can be re-run much faster, and this still runs Elasticsearch & {kib} locally. +** Description: Two commands, run in separate terminals, separate the components that are long-running and slow from those that are ephemeral and fast. Tests can be re-run much faster, and this still runs {es} & {kib} locally. ** `node scripts/functional_tests_server` -*** starts Elasticsearch and {kib} servers +*** starts {es} and {kib} servers *** slow to start *** can be reused for multiple executions of the tests, thereby saving some time when re-running tests *** automatically restarts the {kib} server when relevant changes are detected ** `node scripts/functional_test_runner` -*** runs the tests against {kib} & Elasticsearch servers that were started by `node scripts/functional_tests_server` +*** runs the tests against {kib} & {es} servers that were started by `node scripts/functional_tests_server` *** exit code reports success or failure of the tests 3. Custom option: -** Description: Runs tests against instances of Elasticsearch & {kib} started some other way (like Elastic Cloud, or an instance you are managing in some other way). +** Description: Runs tests against instances of {es} & {kib} started some other way (like Elastic Cloud, or an instance you are managing in some other way). ** just executes the functional tests -** url, credentials, etc. for Elasticsearch and {kib} are specified via environment variables +** url, credentials, etc. for {es} and {kib} are specified via environment variables ** Here's an example that runs against an Elastic Cloud instance. Note that you must run the same branch of tests as the version of {kib} you're testing. + ["source","shell"] @@ -91,15 +91,15 @@ export TEST_THROTTLE_NETWORK=1 node scripts/functional_test_runner --exclude-tag skipCloud ---------- -[float] -===== More about `node scripts/functional_test_runner` +[discrete] +==== More about `node scripts/functional_test_runner` When run without any arguments the `FunctionalTestRunner` automatically loads the configuration in the standard location, but you can override that behavior with the `--config` flag. List configs with multiple --config arguments. -* `--config test/functional/config.js` starts Elasticsearch and {kib} servers with the WebDriver tests configured to run in Chrome. -* `--config test/functional/config.firefox.js` starts Elasticsearch and {kib} servers with the WebDriver tests configured to run in Firefox. -* `--config test/api_integration/config.js` starts Elasticsearch and {kib} servers with the api integration tests configuration. -* `--config test/accessibility/config.ts` starts Elasticsearch and {kib} servers with the WebDriver tests configured to run an accessibility audit using https://www.deque.com/axe/[axe]. +* `--config test/functional/config.js` starts {es} and {kib} servers with the WebDriver tests configured to run in Chrome. +* `--config test/functional/config.firefox.js` starts {es} and {kib} servers with the WebDriver tests configured to run in Firefox. +* `--config test/api_integration/config.js` starts {es} and {kib} servers with the api integration tests configuration. +* `--config test/accessibility/config.ts` starts {es} and {kib} servers with the WebDriver tests configured to run an accessibility audit using https://www.deque.com/axe/[axe]. There are also command line flags for `--bail` and `--grep`, which behave just like their mocha counterparts. For instance, use `--grep=foo` to run only tests that match a regular expression. @@ -108,11 +108,11 @@ Logging can also be customized with `--quiet`, `--debug`, or `--verbose` flags. Use the `--help` flag for more options. -[float] -==== Writing functional tests +[discrete] +=== Writing functional tests -[float] -===== Environment +[discrete] +==== Environment The tests are written in https://mochajs.org[mocha] using https://github.com/elastic/kibana/tree/master/packages/kbn-expect[@kbn/expect] for assertions. @@ -120,8 +120,8 @@ We use https://www.w3.org/TR/webdriver1/[WebDriver Protocol] to run tests in bot The `FunctionalTestRunner` automatically transpiles functional tests using babel, so that tests can use the same ECMAScript features that {kib} source code uses. See {blob}style_guides/js_style_guide.md[style_guides/js_style_guide.md]. -[float] -===== Definitions +[discrete] +==== Definitions **Provider:** @@ -179,8 +179,8 @@ To run tests on Firefox locally, use `config.firefox.js`: node scripts/functional_test_runner --config test/functional/config.firefox.js ----------- -[float] -===== Using the test_user service +[discrete] +==== Using the test_user service Tests should run at the positive security boundry condition, meaning that they should be run with the mimimum privileges required (and documented) and not as the superuser. This prevents the type of regression where additional privleges accidentally become required to perform the same action. @@ -198,8 +198,8 @@ Here we are setting the `test_user` to have the `kibana_user` role and also role Tests should normally setRoles() in the before() and restoreDefaults() in the after(). -[float] -===== Anatomy of a test file +[discrete] +==== Anatomy of a test file This annotated example file shows the basic structure every test suite uses. It starts by importing https://github.com/elastic/kibana/tree/master/packages/kbn-expect[`@kbn/expect`] and defining its default export: an anonymous Test Provider. The test provider then destructures the Provider API for the `getService()` and `getPageObjects()` functions. It uses these functions to collect the dependencies of this suite. The rest of the test file will look pretty normal to mocha.js users. `describe()`, `it()`, `before()` and the lot are used to define suites that happen to automate a browser via services and objects of type `PageObject`. @@ -222,7 +222,7 @@ export default function ({ getService, getPageObject }) { describe('My Test Suite', () => { // most suites start with a before hook that navigates to a specific - // app/page and restores some archives into elasticsearch with esArchiver + // app/page and restores some archives into {es} with esArchiver before(async () => { await Promise.all([ // start with an empty .kibana index @@ -235,7 +235,7 @@ export default function ({ getService, getPageObject }) { }); // right after the before() hook definition, add the teardown steps - // that will tidy up elasticsearch for other test suites + // that will tidy up {es} for other test suites after(async () => { // we unload the empty_kibana archive but not the makelogs // archive because we don't make any changes to it, and subsequent @@ -257,9 +257,9 @@ export default function ({ getService, getPageObject }) { } ---- -[float] +[discrete] [[functional_test_runner_provider_api]] -==== Provider API +=== Provider API The first and only argument to all providers is a Provider API Object. This object can be used to load service/page objects and config/test files. @@ -280,11 +280,11 @@ Within a test Provider the API is exactly the same as the service providers API [horizontal] `loadTestFile(path)`::: Load the test file at path in place. Use this method to nest suites from other files into a higher-level suite -[float] -==== Service Index +[discrete] +=== Service Index -[float] -===== Built-in Services +[discrete] +==== Built-in Services The `FunctionalTestRunner` comes with three built-in services: @@ -304,8 +304,8 @@ The `FunctionalTestRunner` comes with three built-in services: * Exposes lifecycle events for basic coordination. Handlers can return a promise and resolve/fail asynchronously * Phases include: `beforeLoadTests`, `beforeTests`, `beforeEachTest`, `cleanup` -[float] -===== {kib} Services +[discrete] +==== {kib} Services The {kib} functional tests define the vast majority of the actual functionality used by tests. @@ -377,7 +377,7 @@ Full list of services that are used in functional tests can be found here: {blob **Low-level utilities:**::: * es ** Source: {blob}test/common/services/es.ts[test/common/services/es.ts] -** Elasticsearch client +** {es} client ** Higher level options: `kibanaServer.uiSettings` or `esArchiver` * remote ** Source: {blob}test/functional/services/remote/remote.ts[test/functional/services/remote/remote.ts] @@ -387,8 +387,8 @@ Full list of services that are used in functional tests can be found here: {blob ** For searching and manipulating with DOM elements, use `testSubjects` and `find` services ** See the https://seleniumhq.github.io/selenium/docs/api/javascript/[selenium-webdriver docs] for the full API. -[float] -===== Custom Services +[discrete] +==== Custom Services Services are intentionally generic. They can be literally anything (even nothing). Some services have helpers for interacting with a specific types of UI elements, like `pointSeriesVis`, and others are more foundational, like `log` or `config`. Whenever you want to provide some functionality in a reusable package, consider making a custom service. @@ -427,8 +427,8 @@ export default function () { } ----------- -[float] -==== PageObjects +[discrete] +=== PageObjects The purpose for each PageObject is pretty self-explanatory. The visualize PageObject provides helpers for interacting with the visualize app, dashboard is the same for the dashboard app, and so on. @@ -436,13 +436,13 @@ One exception is the "common" PageObject. A holdover from the intern implementat Please add new methods to existing or new services rather than further expanding the CommonPage class. -[float] -==== Gotchas +[discrete] +=== Gotchas Remember that you can’t run an individual test in the file (`it` block) because the whole `describe` needs to be run in order. There should only be one top level `describe` in a file. -[float] -===== Functional Test Timing +[discrete] +==== Functional Test Timing Another important gotcha is writing stable tests by being mindful of timing. All methods on `remote` run asynchronously. It’s better to write interactions that wait for changes on the UI to appear before moving onto the next step. @@ -480,8 +480,8 @@ class AppPage { Writing in this way will ensure your test timings are not flaky or based on assumptions about UI updates after interactions. -[float] -==== Debugging +[discrete] +=== Debugging From the command line run: @@ -503,8 +503,8 @@ const log = getService(‘log’); log.debug(‘done clicking menu’); ----------- -[float] -==== MacOS testing performance tip +[discrete] +=== MacOS testing performance tip macOS users on a machine with a discrete graphics card may see significant speedups (up to 2x) when running tests by changing your terminal emulator's GPU settings. In iTerm2: * Open Preferences (Command + ,) diff --git a/docs/developer/contributing/development-github.asciidoc b/docs/developer/contributing/development-github.asciidoc index 027b4e73aa9de..a6d4e29940487 100644 --- a/docs/developer/contributing/development-github.asciidoc +++ b/docs/developer/contributing/development-github.asciidoc @@ -1,16 +1,16 @@ [[development-github]] -=== How we use git and github +== How we use git and github -[float] -==== Forking +[discrete] +=== Forking We follow the https://help.github.com/articles/fork-a-repo/[GitHub forking model] for collaborating on {kib} code. This model assumes that you have a remote called `upstream` which points to the official {kib} repo, which we'll refer to in later code snippets. -[float] -==== Branching +[discrete] +=== Branching * All work on the next major release goes into master. * Past major release branches are named `{majorVersion}.x`. They contain @@ -24,8 +24,8 @@ if the next patch release is `5.3.1`, work for it should go into the branches. * Where appropriate, we'll backport changes into older release branches. -[float] -==== Commits and Merging +[discrete] +=== Commits and Merging * Feel free to make as many commits as you want, while working on a branch. @@ -38,8 +38,8 @@ explanation of _why_ you made the changes that you did. feature branch, and force-pushing (see below for instructions). * When merging, we'll squash your commits into a single commit. -[float] -===== Rebasing and fixing merge conflicts +[discrete] +==== Rebasing and fixing merge conflicts Rebasing can be tricky, and fixing merge conflicts can be even trickier because it involves force pushing. This is all compounded by the fact @@ -106,7 +106,7 @@ hint: See the 'Note about fast-forwards' in 'git push --help' for details. Assuming you've successfully rebased and you're happy with the code, you should force push instead. -[float] -==== Creating a pull request +[discrete] +=== Creating a pull request See <> for the next steps on getting your code changes merged into {kib}. \ No newline at end of file diff --git a/docs/developer/contributing/development-pull-request.asciidoc b/docs/developer/contributing/development-pull-request.asciidoc index 5d3c30fec7383..070eff449af5b 100644 --- a/docs/developer/contributing/development-pull-request.asciidoc +++ b/docs/developer/contributing/development-pull-request.asciidoc @@ -1,16 +1,16 @@ [[development-pull-request]] -=== Submitting a pull request +== Submitting a pull request -[float] -==== What Goes Into a Pull Request +[discrete] +=== What Goes Into a Pull Request * Please include an explanation of your changes in your PR description. * Links to relevant issues, external resources, or related PRs are very important and useful. * Please update any tests that pertain to your code, and add new tests where appropriate. * Update or add docs when appropriate. Read more about <>. -[float] -==== Submitting a Pull Request +[discrete] +=== Submitting a Pull Request 1. Push your local changes to your forked copy of the repository and submit a pull request. 2. Describe what your changes do and mention the number of the issue where discussion has taken place, e.g., “Closes #123″. @@ -22,8 +22,8 @@ Always submit your pull against master unless the bug is only present in an olde Then sit back and wait. There will probably be discussion about the Pull Request and, if any changes are needed, we'll work with you to get your Pull Request merged into {kib}. -[float] -==== What to expect during the pull request review process +[discrete] +=== What to expect during the pull request review process Most PRs go through several iterations of feedback and updates. Depending on the scope and complexity of the PR, the process can take weeks. Please be patient and understand we hold our code base to a high standard. diff --git a/docs/developer/contributing/development-tests.asciidoc b/docs/developer/contributing/development-tests.asciidoc index b470ea61669b2..78a2a90b69ce5 100644 --- a/docs/developer/contributing/development-tests.asciidoc +++ b/docs/developer/contributing/development-tests.asciidoc @@ -1,10 +1,10 @@ [[development-tests]] -=== Testing +== Testing To ensure that your changes will not break other functionality, please run the test suite and build (<>) before submitting your Pull Request. -[float] -==== Running specific {kib} tests +[discrete] +=== Running specific {kib} tests The following table outlines possible test file locations and how to invoke them: @@ -47,8 +47,8 @@ Examples: - Run the entire elasticsearch_service test suite: string: ``` yarn test:ftr:server –config test/api_integration/config.js yarn test:ftr:runner –config test/api_integration/config -[float] -==== Cross-browser compatibility +[discrete] +=== Cross-browser compatibility **Testing IE on OS X** @@ -71,8 +71,8 @@ your computer name). `http://computer.local:5601` to test {kib}. * Alternatively you can use browserstack -[float] -==== Running browser automation tests +[discrete] +=== Running browser automation tests Check out <> to learn more about how you can run and develop functional tests for {kib} core and plugins. @@ -80,17 +80,17 @@ and develop functional tests for {kib} core and plugins. You can also look into the {kib-repo}tree/{branch}/scripts/README.md[Scripts README.md] to learn more about using the node scripts we provide for building {kib}, running integration tests, and starting up {kib} and -Elasticsearch while you develop. +{es} while you develop. -[float] +[discrete] ==== More testing information: * <> * <> * <> -include::development-functional-tests.asciidoc[] +include::development-functional-tests.asciidoc[leveloffset=+1] -include::development-unit-tests.asciidoc[] +include::development-unit-tests.asciidoc[leveloffset=+1] -include::development-accessibility-tests.asciidoc[] \ No newline at end of file +include::development-accessibility-tests.asciidoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/developer/contributing/development-unit-tests.asciidoc b/docs/developer/contributing/development-unit-tests.asciidoc index 3e839f207bcce..fba9a41b2ce80 100644 --- a/docs/developer/contributing/development-unit-tests.asciidoc +++ b/docs/developer/contributing/development-unit-tests.asciidoc @@ -1,11 +1,11 @@ [[development-unit-tests]] -==== Unit testing frameworks +== Unit testing frameworks {kib} is migrating unit testing from `Mocha` to `Jest`. Legacy unit tests still exist in Mocha but all new unit tests should be written in Jest. -[float] -===== Mocha (legacy) +[discrete] +=== Mocha (legacy) Mocha tests are contained in `__tests__` directories. @@ -16,8 +16,8 @@ Mocha tests are contained in `__tests__` directories. yarn test:mocha ----------- -[float] -==== Jest +[discrete] +== Jest Jest tests are stored in the same directory as source code files with the `.test.{js,mjs,ts,tsx}` suffix. *Running Jest Unit Tests* @@ -27,8 +27,8 @@ Jest tests are stored in the same directory as source code files with the `.test yarn test:jest ----------- -[float] -====== Writing Jest Unit Tests +[discrete] +==== Writing Jest Unit Tests In order to write those tests there are two main things you need to be aware of. The first one is the different between `jest.mock` and `jest.doMock` @@ -37,8 +37,8 @@ test files with `babel-jest` both techniques are needed specially for the tests implemented on Typescript in order to benefit from the auto-inference types feature. -[float] -====== Jest.mock vs Jest.doMock +[discrete] +==== Jest.mock vs Jest.doMock Both methods are essentially the same on their roots however the `jest.mock` calls will get hoisted to the top of the file and can only reference variables @@ -47,8 +47,8 @@ reference pretty much any variable we want, however we have to assure those refe variables are instantiated at the time we need them which lead us to the next section where we'll talk about our jest mock files pattern. -[float] -====== Jest Mock Files Pattern +[discrete] +==== Jest Mock Files Pattern Specially on typescript it is pretty common to have in unit tests `jest.doMock` calls which reference for example imported types. Any error @@ -76,9 +76,9 @@ like: `import * as Mocks from './mymodule.test.mocks'`, or just `import './mymodule.test.mocks'` if there isn't anything exported to be used. -[float] +[discrete] [[debugging-unit-tests]] -===== Debugging Unit Tests +=== Debugging Unit Tests The standard `yarn test` task runs several sub tasks and can take several minutes to complete, making debugging failures pretty painful. @@ -127,8 +127,8 @@ description. image:http://i.imgur.com/DwHxgfq.png[Browser test debugging] -[float] -===== Unit Testing Plugins +[discrete] +=== Unit Testing Plugins This should work super if you’re using the https://github.com/elastic/kibana/tree/master/packages/kbn-plugin-generator[Kibana diff --git a/docs/developer/contributing/index.asciidoc b/docs/developer/contributing/index.asciidoc index 4f987f31cf1f6..99ab83bc2f073 100644 --- a/docs/developer/contributing/index.asciidoc +++ b/docs/developer/contributing/index.asciidoc @@ -23,7 +23,7 @@ Read <> to get your environment up and running, the Please make sure you have signed the [Contributor License Agreement](http://www.elastic.co/contributor-agreement/). We are not asking you to assign copyright to us, but to give us the right to distribute your code without restriction. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the CLA once. -[float] +[discrete] [[kibana-localization]] === Localization @@ -32,7 +32,7 @@ Read <> for details on our localization prac Note that we cannot support accepting contributions to the translations from any source other than the translators we have engaged to do the work. We are still to develop a proper process to accept any contributed translations. We certainly appreciate that people care enough about the localization effort to want to help improve the quality. We aim to build out a more comprehensive localization process for the future and will notify you once contributions can be supported, but for the time being, we are not able to incorporate suggestions. -[float] +[discrete] [[kibana-release-notes-process]] === Release Notes Process @@ -43,7 +43,7 @@ access to GitHub labels. The Release Notes summarize what the PRs accomplish in language that is meaningful to users. To generate the Release Notes, the team runs a script against this repo to collect the merged PRs against the release. -[float] +[discrete] ==== Create the Release Notes text The text that appears in the Release Notes is pulled directly from your PR title, or a single paragraph of text that you specify in the PR description. @@ -59,7 +59,7 @@ When you create the Release Notes text, use the following best practices: * When you create a bug fix PR, start with `Fixes`. * When you create a deprecation PR, start with `Deprecates`. -[float] +[discrete] ==== Add your labels [arabic] @@ -72,18 +72,18 @@ When you create the Release Notes text, use the following best practices: * To **NOT** include your changes in the Release Notes, use `release_note:skip`. -include::development-github.asciidoc[] +include::development-github.asciidoc[leveloffset=+1] -include::development-tests.asciidoc[] +include::development-tests.asciidoc[leveloffset=+1] -include::interpreting-ci-failures.asciidoc[] +include::interpreting-ci-failures.asciidoc[leveloffset=+1] -include::development-documentation.asciidoc[] +include::development-documentation.asciidoc[leveloffset=+1] -include::development-pull-request.asciidoc[] +include::development-pull-request.asciidoc[leveloffset=+1] -include::kibana-issue-reporting.asciidoc[] +include::kibana-issue-reporting.asciidoc[leveloffset=+1] -include::pr-review.asciidoc[] +include::pr-review.asciidoc[leveloffset=+1] -include::linting.asciidoc[] +include::linting.asciidoc[leveloffset=+1] diff --git a/docs/developer/contributing/interpreting-ci-failures.asciidoc b/docs/developer/contributing/interpreting-ci-failures.asciidoc index 86c4f22b4f894..f07a2baa7aecd 100644 --- a/docs/developer/contributing/interpreting-ci-failures.asciidoc +++ b/docs/developer/contributing/interpreting-ci-failures.asciidoc @@ -1,19 +1,19 @@ [[interpreting-ci-failures]] -=== Interpreting CI Failures +== Interpreting CI Failures {kib} CI uses a Jenkins feature called "Pipelines" to automate testing of the code in pull requests and on tracked branches. Pipelines are defined within the repository via the `Jenkinsfile` at the root of the project. More information about Jenkins Pipelines can be found link:https://jenkins.io/doc/book/pipeline/[in the Jenkins book]. -[float] -==== Github Checks +[discrete] +=== Github Checks When a test fails it will be reported to Github via Github Checks. We currently bucket tests into several categories which run in parallel to make CI faster. Groups like `ciGroup{X}` get a single check in Github, and other tests like linting, or type checks, get their own checks. Clicking the link next to the check in the conversation tab of a pull request will take you to the log output from that section of the tests. If that log output is truncated, or doesn't clearly identify what happened, you can usually get more complete information by visiting Jenkins directly. -[float] -==== Viewing Job Executions in Jenkins +[discrete] +=== Viewing Job Executions in Jenkins To view the results of a job execution in Jenkins, either click the link in the comment left by `@elasticmachine` or search for the `kibana-ci` check in the list at the bottom of the PR. This link will take you to the top-level page for the specific job execution that failed. @@ -24,8 +24,8 @@ image::images/jenkins/job_view.png[] 3. *Google Cloud Storage (GCS) Upload Report:* Link to the screen which lists out the artifacts uploaded to GCS during this job execution. 4. *Pipeline Steps:*: A breakdown of the pipline that was executed, along with individual log output for each step in the pipeline. -[float] -==== Viewing ciGroup/test Logs +[discrete] +=== Viewing ciGroup/test Logs To view the logs for a failed specific ciGroup, jest, mocha, type checkers, linters, etc., click on the *Pipeline Steps* link in from the Job page. diff --git a/docs/developer/contributing/kibana-issue-reporting.asciidoc b/docs/developer/contributing/kibana-issue-reporting.asciidoc index 36c50b612d675..63366ae2aa6bb 100644 --- a/docs/developer/contributing/kibana-issue-reporting.asciidoc +++ b/docs/developer/contributing/kibana-issue-reporting.asciidoc @@ -1,8 +1,8 @@ [[kibana-issue-reporting]] -=== Effective issue reporting in {kib} +== Effective issue reporting in {kib} -[float] -==== Voicing the importance of an issue +[discrete] +=== Voicing the importance of an issue We seriously appreciate thoughtful comments. If an issue is important to you, add a comment with a solid write up of your use case and explain @@ -17,8 +17,8 @@ https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments[ thumbs up reaction] on the issue itself and on the comment which best summarizes your thoughts. -[float] -==== "`My issue isn’t getting enough attention`" +[discrete] +=== "`My issue isn’t getting enough attention`" First of all, *sorry about that!* We want you to have a great time with {kib}. @@ -31,8 +31,8 @@ more pressing issues. Feel free to bump your issues if you think they’ve been neglected for a prolonged period. -[float] -==== "`I want to help!`" +[discrete] +=== "`I want to help!`" *Now we’re talking*. If you have a bug fix or new feature that you would like to contribute to {kib}, please *find or open an issue about it diff --git a/docs/developer/contributing/linting.asciidoc b/docs/developer/contributing/linting.asciidoc index 234bd90478907..0d05afa504538 100644 --- a/docs/developer/contributing/linting.asciidoc +++ b/docs/developer/contributing/linting.asciidoc @@ -1,5 +1,5 @@ [[kibana-linting]] -=== Linting +== Linting A note about linting: We use http://eslint.org[eslint] to check that the link:STYLEGUIDE.md[styleguide] is being followed. It runs in a @@ -34,8 +34,8 @@ for your editor, and browse our https://github.com/elastic/kibana/blob/master/.editorconfig[`.editorconfig`] file to see what config rules we set up. -[float] -==== Setup Guide for VS Code Users +[discrete] +== Setup Guide for VS Code Users Note that for VSCode, to enable "`live`" linting of TypeScript (and other) file types, you will need to modify your local settings, as shown diff --git a/docs/developer/contributing/pr-review.asciidoc b/docs/developer/contributing/pr-review.asciidoc index ebab3b24aaaee..885725795b0b9 100644 --- a/docs/developer/contributing/pr-review.asciidoc +++ b/docs/developer/contributing/pr-review.asciidoc @@ -1,5 +1,5 @@ [[pr-review]] -=== Pull request review guidelines +== Pull request review guidelines Every change made to {kib} must be held to a high standard, and while the responsibility for quality in a pull request ultimately lies with the author, {kib} team members have the responsibility as reviewers to verify during their review process. @@ -10,24 +10,24 @@ It is not expected nor intended for a PR review to take the shape of this docume While the review process is always done by Elastic staff members, these guidelines apply to all pull requests regardless of whether they are authored by community members or Elastic staff. -[float] -==== Target audience +[discrete] +=== Target audience The target audience for this document are pull request reviewers. For {kib} maintainers, the PR review is the only part of the contributing process in which we have complete control. The author of any given pull request may not be up to speed on the latest expectations we have for pull requests, and they may have never read our guidelines at all. It's our responsibility as reviewers to guide folks through this process, but it's hard to do that consistently without a common set of documented principles. Pull request authors can benefit from reading this document as well because it'll help establish a common set of expectations between authors and reviewers early. -[float] -==== Reject fast +[discrete] +=== Reject fast Every pull request is different, and before reviewing any given PR, reviewers should consider the optimal way to approach the PR review so that if the change is ultimately rejected, it is done so as early in the process as possible. For example, a reviewer may want to do a product level review as early as possible for a PR that includes a new UI feature. On the other hand, perhaps the author is submitting a new feature that has been rejected in the past due to key architectural decisions, in which case it may be appropriate for the reviewer to focus on the soundness of the architecture before diving into anything else. -[float] -==== The big three +[discrete] +=== The big three There are a lot of discrete requirements and guidelines we want to follow in all of our pull requests, but three things in particular stand out as important above all the rest. @@ -58,20 +58,20 @@ This isn't simply a question of enough test files. The code in the tests themsel All of our code should have unit tests that verify its behaviors, including not only the "happy path", but also edge cases, error handling, etc. When you change an existing API of a module, then there should always be at least one failing unit test, which in turn means we need to verify that all code consuming that API properly handles the change if necessary. For modules at a high enough level, this will mean we have breaking change in the product, which we'll need to handle accordingly. -In addition to extensive unit test coverage, PRs should include relevant functional and integration tests. In some cases, we may simply be testing a programmatic interface (e.g. a service) that is integrating with the file system, the network, Elasticsearch, etc. In other cases, we'll be testing REST APIs over HTTP or comparing screenshots/snapshots with prior known acceptable state. In the worst case, we are doing browser-based functional testing on a running instance of {kib} using selenium. +In addition to extensive unit test coverage, PRs should include relevant functional and integration tests. In some cases, we may simply be testing a programmatic interface (e.g. a service) that is integrating with the file system, the network, {es}, etc. In other cases, we'll be testing REST APIs over HTTP or comparing screenshots/snapshots with prior known acceptable state. In the worst case, we are doing browser-based functional testing on a running instance of {kib} using selenium. Enhancements are pretty much always going to have extensive unit tests as a base as well as functional and integration testing. Bug fixes should always include regression tests to ensure that same bug does not manifest again in the future. -- -[float] -==== Product level review +[discrete] +=== Product level review Reviewers are not simply evaluating the code itself, they are also evaluating the quality of the user-facing change in the product. This generally means they need to check out the branch locally and "play around" with it. In addition to the "do we want this change in the product" details, the reviewer should be looking for bugs and evaluating how approachable and useful the feature is as implemented. Special attention should be given to error scenarios and edge cases to ensure they are all handled well within the product. -[float] -==== Consistency, style, readability +[discrete] +=== Consistency, style, readability Having a relatively consistent codebase is an important part of us building a sustainable project. With dozens of active contributors at any given time, we rely on automation to help ensure consistency - we enforce a comprehensive set of linting rules through CI. We're also rolling out prettier to make this even more automatic. @@ -86,8 +86,8 @@ When in doubt, relying on "prior art" in the codebase, especially in and around There may also be times when a person is inspired by a particular contribution to introduce a new way to style code that we already have different style guidelines or "prior art" for. It's OK to bring this up in a pull request, but ultimately that discussion should branch off into a separate issue or pull request to update the appropriate guide. If this change is prompted by a reviewer, then the original PR should not be blocked on this. If the change is prompted by the author, then they can either update the PR to be consistent with our existing guidelines (preferred) or they can choose to block the PR entirely on that separate styleguide discussion. -[float] -==== Nitpicking +[discrete] +=== Nitpicking Nitpicking is when a reviewer identifies trivial and unimportant details in a pull request and asks the author to change them. This is a completely subjective category that is impossible to define universally, and it's equally impractical to define a blanket policy on nitpicking that everyone will be happy with. @@ -96,14 +96,14 @@ Reviewers should feel comfortable giving any feedback they have on a pull reques Often, reviewers have an opinion about whether the feedback they are about to give is a nitpick or not. While not required, it can be really helpful to identify that feedback as such, for example "nit: a newline after this would be helpful". This helps the author understand your intention. -[float] -==== Handling disagreements +[discrete] +=== Handling disagreements Conflicting opinions between reviewers and authors happen, and sometimes it is hard to reconcile those opinions. Ideally folks can work together in the spirit of these guidelines toward a consensus, but if that doesn't work out it may be best to bring a third person into the discussion. Our pull requests generally have two reviewers, so an appropriate third person may already be obvious. Otherwise, reach out to the functional area that is most appropriate or to technical leadership if an area isn't obvious. -[float] -==== Inappropriate review feedback +[discrete] +=== Inappropriate review feedback Whether or not a bit of feedback is appropriate for a pull request is often dependent on the motivation for giving the feedback in the first place. @@ -112,8 +112,8 @@ _Demanding_ an author make changes based primarily on the mindset of "how would Inflammatory feedback such as "this is crap" isn't feedback at all. It's both mean and unhelpful, and it is never appropriate. -[float] -==== A checklist +[discrete] +=== A checklist Establishing a comprehensive checklist for all of the things that should happen in all possible pull requests is impractical, but that doesn't mean we lack a concrete set of minimum requirements that we can enumerate. The following items should be double checked for any pull request: diff --git a/docs/developer/getting-started/building-kibana.asciidoc b/docs/developer/getting-started/building-kibana.asciidoc index e1f1ca336a5da..72054b1628fc2 100644 --- a/docs/developer/getting-started/building-kibana.asciidoc +++ b/docs/developer/getting-started/building-kibana.asciidoc @@ -1,5 +1,5 @@ [[building-kibana]] -=== Building a {kib} distributable +== Building a {kib} distributable The following commands will build a {kib} production distributable. @@ -15,8 +15,8 @@ You can get all build options using the following command: yarn build --help ---- -[float] -==== Building OS packages +[discrete] +=== Building OS packages Packages are built using fpm, dpkg, and rpm. Package building has only been tested on Linux and is not supported on any other platform. diff --git a/docs/developer/getting-started/debugging.asciidoc b/docs/developer/getting-started/debugging.asciidoc index b369dcda748af..a3fb12ec1f6a3 100644 --- a/docs/developer/getting-started/debugging.asciidoc +++ b/docs/developer/getting-started/debugging.asciidoc @@ -1,15 +1,15 @@ [[kibana-debugging]] -=== Debugging {kib} +== Debugging {kib} For information about how to debug unit tests, refer to <>. -[float] -==== Server Code +[discrete] +=== Server Code `yarn debug` will start the server with Node's inspect flag. {kib}'s development mode will start three processes on ports `9229`, `9230`, and `9231`. Chrome's developer tools need to be configured to connect to all three connections. Add `localhost:` for each {kib} process in Chrome's developer tools connection tab. -[float] -==== Instrumenting with Elastic APM +[discrete] +=== Instrumenting with Elastic APM {kib} ships with the https://github.com/elastic/apm-agent-nodejs[Elastic APM Node.js Agent] @@ -18,7 +18,7 @@ built-in for debugging purposes. Its default configuration is meant to be used by core {kib} developers only, but it can easily be re-configured to your needs. In its default configuration it’s disabled and will, once enabled, send APM data to a -centrally managed Elasticsearch cluster accessible only to Elastic +centrally managed {es} cluster accessible only to Elastic employees. To change the location where data is sent, use the diff --git a/docs/developer/getting-started/development-plugin-resources.asciidoc b/docs/developer/getting-started/development-plugin-resources.asciidoc index dfe8efc4fef57..8f81138b81ed7 100644 --- a/docs/developer/getting-started/development-plugin-resources.asciidoc +++ b/docs/developer/getting-started/development-plugin-resources.asciidoc @@ -1,14 +1,14 @@ [[development-plugin-resources]] -=== Plugin Resources +== Plugin Resources Here are some resources that are helpful for getting started with plugin development. -[float] -==== Some light reading +[discrete] +=== Some light reading If you haven't already, start with <>. If you are planning to add your plugin to the {kib} repo, read the <> guide, if you are building a plugin externally, read <>. In both cases, read up on our recommended <>. -[float] -==== Creating an empty plugin +[discrete] +=== Creating an empty plugin You can use the <> to get a basic structure for a new plugin. Plugins that are not part of the {kib} repo should be developed inside the `plugins` folder. If you are building a new plugin to check in to the {kib} repo, @@ -18,15 +18,15 @@ you will choose between a few locations: - {kib-repo}tree/{branch}/src/plugins[src/plugins] for open source licensed plugins - {kib-repo}tree/{branch}/examples[examples] for developer example plugins (these will not be included in the distributables) -[float] -==== Elastic UI Framework +[discrete] +=== Elastic UI Framework If you're developing a plugin that has a user interface, take a look at our https://elastic.github.io/eui[Elastic UI Framework]. It documents the CSS and React components we use to build {kib}'s user interface. You're welcome to use these components, but be aware that they are rapidly evolving, and we might introduce breaking changes that will disrupt your plugin's UI. -[float] -==== TypeScript Support +[discrete] +=== TypeScript Support We recommend your plugin code is written in http://www.typescriptlang.org/[TypeScript]. To enable TypeScript support, create a `tsconfig.json` file at the root of your plugin that looks something like this: @@ -48,14 +48,14 @@ TypeScript code is automatically converted into JavaScript during development, but not in the distributable version of {kib}. If you use the {kib-repo}blob/{branch}/packages/kbn-plugin-helpers[@kbn/plugin-helpers] to build your plugin, then your `.ts` and `.tsx` files will be permanently transpiled before your plugin is archived. If you have your own build process, make sure to run the TypeScript compiler on your source files and ship the compilation output so that your plugin will work with the distributable version of {kib}. -[float] -==== {kib} platform migration guide +[discrete] +=== {kib} platform migration guide {kib-repo}blob/{branch}/src/core/MIGRATION.md#migrating-legacy-plugins-to-the-new-platform[This guide] provides an action plan for moving a legacy plugin to the new platform. -[float] -==== Externally developed plugins +[discrete] +=== Externally developed plugins If you are building a plugin outside of the {kib} repo, read <>. diff --git a/docs/developer/getting-started/index.asciidoc b/docs/developer/getting-started/index.asciidoc index 4ca41a6f0dee4..14cb3a63c6943 100644 --- a/docs/developer/getting-started/index.asciidoc +++ b/docs/developer/getting-started/index.asciidoc @@ -3,7 +3,7 @@ Get started building your own plugins, or contributing directly to the {kib} repo. -[float] +[discrete] [[get-kibana-code]] === Get the code @@ -15,7 +15,7 @@ git clone https://github.com/[YOUR_USERNAME]/kibana.git kibana cd kibana ---- -[float] +[discrete] === Install dependencies Install the version of Node.js listed in the `.node-version` file. This @@ -67,11 +67,11 @@ corrupted packages in your yarn cache which you can clean with: yarn cache clean ---- -[float] +[discrete] === Configure environmental settings [[increase-nodejs-heap-size]] -[float] +[discrete] ==== Increase node.js heap size {kib} is a big project and for some commands it can happen that the @@ -81,10 +81,10 @@ by setting the `--max_old_space_size` option on the command line. To set the limit for all commands, simply add the following line to your shell config: `export NODE_OPTIONS="--max_old_space_size=2048"`. -[float] -=== Run Elasticsearch +[discrete] +=== Run {es} -Run the latest Elasticsearch snapshot. Specify an optional license with the `--license` flag. +Run the latest {es} snapshot. Specify an optional license with the `--license` flag. [source,bash] ---- @@ -96,7 +96,7 @@ yarn es snapshot --license trial Read about more options for <>, like connecting to a remote host, running from source, preserving data inbetween runs, running remote cluster, etc. -[float] +[discrete] === Run {kib} In another terminal window, start up {kib}. Include developer examples by adding an optional `--run-examples` flag. @@ -110,13 +110,13 @@ View all available options by running `yarn start --help` Read about more advanced options for <>. -[float] +[discrete] === Code away! You are now ready to start developing. Changes to your files should be picked up automatically. Server side changes will cause the {kib} server to reboot. -[float] +[discrete] === More information * <> @@ -129,12 +129,12 @@ cause the {kib} server to reboot. * <> -include::running-kibana-advanced.asciidoc[] +include::running-kibana-advanced.asciidoc[leveloffset=+1] -include::sample-data.asciidoc[] +include::sample-data.asciidoc[leveloffset=+1] -include::debugging.asciidoc[] +include::debugging.asciidoc[leveloffset=+1] -include::building-kibana.asciidoc[] +include::building-kibana.asciidoc[leveloffset=+1] -include::development-plugin-resources.asciidoc[] \ No newline at end of file +include::development-plugin-resources.asciidoc[leveloffset=+1] \ No newline at end of file diff --git a/docs/developer/getting-started/running-kibana-advanced.asciidoc b/docs/developer/getting-started/running-kibana-advanced.asciidoc index f6c6d7c26ab70..8b598c7088167 100644 --- a/docs/developer/getting-started/running-kibana-advanced.asciidoc +++ b/docs/developer/getting-started/running-kibana-advanced.asciidoc @@ -1,5 +1,5 @@ [[running-kibana-advanced]] -=== Running {kib} +== Running {kib} Change to your local {kib} directory. Start the development server. @@ -23,8 +23,8 @@ By default, you can log in with username `elastic` and password `changeme`. See the `--help` options on `yarn es ` if you’d like to configure a different password. -[float] -==== Running {kib} in Open-Source mode +[discrete] +=== Running {kib} in Open-Source mode If you’re looking to only work with the open-source software, supply the license type to `yarn es`: @@ -41,8 +41,8 @@ And start {kib} with only open-source code: yarn start --oss ---- -[float] -==== Unsupported URL Type +[discrete] +=== Unsupported URL Type If you’re installing dependencies and seeing an error that looks something like @@ -56,9 +56,9 @@ need to run `yarn kbn bootstrap`. For more info, see link:#setting-up-your-development-environment[Setting Up Your Development Environment] above. -[float] +[discrete] [[customize-kibana-yml]] -==== Customizing `config/kibana.dev.yml` +=== Customizing `config/kibana.dev.yml` The `config/kibana.yml` file stores user configuration directives. Since this file is checked into source control, however, developer @@ -70,8 +70,8 @@ non-dev version and accepts any of the https://www.elastic.co/guide/en/kibana/current/settings.html[standard settings]. -[float] -==== Potential Optimization Pitfalls +[discrete] +=== Potential Optimization Pitfalls * Webpack is trying to include a file in the bundle that I deleted and is now complaining about it is missing @@ -79,9 +79,9 @@ is now complaining about it is missing directory, but webpack isn’t adapting * (if you discover other scenarios, please send a PR!) -[float] -==== Setting Up SSL +[discrete] +=== Setting Up SSL {kib} includes self-signed certificates that can be used for development purposes in the browser and for communicating with -Elasticsearch: `yarn start --ssl` & `yarn es snapshot --ssl`. \ No newline at end of file +{es}: `yarn start --ssl` & `yarn es snapshot --ssl`. \ No newline at end of file diff --git a/docs/developer/getting-started/sample-data.asciidoc b/docs/developer/getting-started/sample-data.asciidoc index 376211ceb2634..0d313cbabe64e 100644 --- a/docs/developer/getting-started/sample-data.asciidoc +++ b/docs/developer/getting-started/sample-data.asciidoc @@ -1,17 +1,17 @@ [[sample-data]] -=== Installing sample data +== Installing sample data -There are a couple ways to easily get data ingested into Elasticsearch. +There are a couple ways to easily get data ingested into {es}. -[float] -==== Sample data packages available for one click installation +[discrete] +=== Sample data packages available for one click installation The easiest is to install one or more of our vailable sample data packages. If you have no data, you should be prompted to install when running {kib} for the first time. You can also access and install the sample data packages by going to the home page and clicking "add sample data". -[float] -==== makelogs script +[discrete] +=== makelogs script The provided `makelogs` script will generate sample data. @@ -22,10 +22,10 @@ node scripts/makelogs --auth : The default username and password combination are `elastic:changeme` -Make sure to execute `node scripts/makelogs` *after* elasticsearch is up and running! +Make sure to execute `node scripts/makelogs` *after* {es} is up and running! -[float] -==== CSV upload +[discrete] +=== CSV upload If running with a platinum or trial license, you can also use the CSV uploader provided inside the Machine learning app. Navigate to the Data visualizer to upload your data from a file. \ No newline at end of file diff --git a/docs/developer/plugin/external-plugin-functional-tests.asciidoc b/docs/developer/plugin/external-plugin-functional-tests.asciidoc index 44f636d627011..706bf6af8ed9b 100644 --- a/docs/developer/plugin/external-plugin-functional-tests.asciidoc +++ b/docs/developer/plugin/external-plugin-functional-tests.asciidoc @@ -1,10 +1,10 @@ [[external-plugin-functional-tests]] -=== Functional Tests for Plugins outside the {kib} repo +== Functional Tests for Plugins outside the {kib} repo Plugins use the `FunctionalTestRunner` by running it out of the {kib} repo. Ensure that your {kib} Development Environment is setup properly before continuing. -[float] -==== Writing your own configuration +[discrete] +=== Writing your own configuration Every project or plugin should have its own `FunctionalTestRunner` config file. Just like {kib}'s, this config file will define all of the test files to load, providers for Services and PageObjects, as well as configuration options for certain services. @@ -82,8 +82,8 @@ From the root of your repo you should now be able to run the `FunctionalTestRunn node ../../kibana/scripts/functional_test_runner ----------- -[float] -==== Using esArchiver +[discrete] +=== Using esArchiver We're working on documentation for this, but for now the best place to look is the original {kib-repo}/issues/10359[pull request]. diff --git a/docs/developer/plugin/external-plugin-localization.asciidoc b/docs/developer/plugin/external-plugin-localization.asciidoc index c151832ab53fa..d30dec1a8f46b 100644 --- a/docs/developer/plugin/external-plugin-localization.asciidoc +++ b/docs/developer/plugin/external-plugin-localization.asciidoc @@ -1,10 +1,10 @@ [[external-plugin-localization]] -=== Localization for plugins outside the {kib} repo +== Localization for plugins outside the {kib} repo To introduce localization for your plugin, use our i18n tool to create IDs and default messages. You can then extract these IDs with respective default messages into localization JSON files for {kib} to use when running your plugin. -[float] -==== Adding localization to your plugin +[discrete] +=== Adding localization to your plugin You must add a `translations` directory at the root of your plugin. This directory will contain the translation files that {kib} uses. @@ -19,8 +19,8 @@ You must add a `translations` directory at the root of your plugin. This directo ----------- -[float] -==== Using {kib} i18n tooling +[discrete] +=== Using {kib} i18n tooling To simplify the localization process, {kib} provides tools for the following functions: * Verify all translations have translatable strings and extract default messages from templates @@ -51,8 +51,8 @@ An example {kib} `.i18nrc.json` is {blob}.i18nrc.json[here]. Full documentation about i18n tooling is {blob}src/dev/i18n/README.md[here]. -[float] -==== Extracting default messages +[discrete] +=== Extracting default messages To extract the default messages from your plugin, run the following command: ["source","shell"] @@ -62,8 +62,8 @@ node scripts/i18n_extract --output-dir ./translations --include-config ../kibana This outputs a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. -[float] -==== Checking i18n messages +[discrete] +=== Checking i18n messages Checking i18n does the following: @@ -80,8 +80,8 @@ node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc. ----------- -[float] -==== Implementing i18n in the UI +[discrete] +=== Implementing i18n in the UI {kib} relies on several UI frameworks (ReactJS and AngularJS) and requires localization in different environments (browser and NodeJS). @@ -97,8 +97,8 @@ so both React and AngularJS frameworks use the same engine and the same message syntax. -[float] -===== i18n for vanilla JavaScript +[discrete] +==== i18n for vanilla JavaScript ["source","js"] ----------- @@ -111,8 +111,8 @@ export const HELLO_WORLD = i18n.translate('hello.wonderful.world', { Full details are {kib-repo}tree/master/packages/kbn-i18n#vanilla-js[here]. -[float] -===== i18n for React +[discrete] +==== i18n for React To localize strings in React, use either `FormattedMessage` or `i18n.translate`. @@ -137,8 +137,8 @@ Full details are {kib-repo}tree/master/packages/kbn-i18n#react[here]. -[float] -===== i18n for Angular +[discrete] +==== i18n for Angular You are encouraged to use `i18n.translate()` by statically importing `i18n` from `@kbn/i18n` wherever possible in your Angular code. Angular wrappers use the translation `service` with the i18n engine under the hood. @@ -156,8 +156,8 @@ The translation directive has the following syntax: Full details are {kib-repo}tree/master/packages/kbn-i18n#angularjs[here]. -[float] -==== Resources +[discrete] +=== Resources To learn more about i18n tooling, see {blob}src/dev/i18n/README.md[i18n dev tooling]. diff --git a/docs/developer/plugin/index.asciidoc b/docs/developer/plugin/index.asciidoc index 73f1d2c908fa7..dd83cf234dea4 100644 --- a/docs/developer/plugin/index.asciidoc +++ b/docs/developer/plugin/index.asciidoc @@ -9,9 +9,9 @@ The {kib} plugin interfaces are in a state of constant development. We cannot p Most developers who contribute code directly to the {kib} repo are writing code inside plugins, so our <> docs are the best place to start. However, there are a few differences when developing plugins outside the {kib} repo. These differences are covered here. -[float] +[discrete] [[automatic-plugin-generator]] -==== Automatic plugin generator +=== Automatic plugin generator We recommend that you kick-start your plugin by generating it with the {kib-repo}tree/{branch}/packages/kbn-plugin-generator[Kibana Plugin Generator]. Run the following in the {kib} repo, and you will be asked a couple questions, see some progress bars, and have a freshly generated plugin ready for you to play with in {kib}'s `plugins` folder. @@ -20,7 +20,7 @@ We recommend that you kick-start your plugin by generating it with the {kib-repo node scripts/generate_plugin my_plugin_name # replace "my_plugin_name" with your desired plugin name ----------- -[float] +[discrete] === Plugin location The {kib} directory must be named `kibana`, and your plugin directory should be located in the root of `kibana` in a `plugins` directory, for example: @@ -37,6 +37,6 @@ The {kib} directory must be named `kibana`, and your plugin directory should be * <> * <> -include::external-plugin-functional-tests.asciidoc[] +include::external-plugin-functional-tests.asciidoc[leveloffset=+1] -include::external-plugin-localization.asciidoc[] +include::external-plugin-localization.asciidoc[leveloffset=+1]