ab8a2f7427
* Initial conversion to asciidoc * Update and split migration guide * Convert MIGRATION_EXAMPLES to asciidoc * build with --focus flag * convert migration guide to asciidoc * cleanup migration_examples * fix wrong Heading size * update links in docs * Apply suggestions from code review Co-authored-by: Rudolf Meijering <skaapgif@gmail.com> * Apply suggestions from code review Co-authored-by: Rudolf Meijering <skaapgif@gmail.com> * add tooling section * explain purpose of each lifecycle method * cleanup docs * cleanup p2 * fix wrong link * resturcture core docs * fix wrong link * update missing links * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * address comments * add a commenta about plugin-helpers preconfigured * improve density of tables * fix lik * remove links to the migration guide * address comments * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * address @gchaps comments * Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * change format of ES client change list Co-authored-by: Josh Dover <me@joshdover.com> Co-authored-by: Rudolf Meijering <skaapgif@gmail.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
154 lines
6 KiB
Plaintext
154 lines
6 KiB
Plaintext
[[development-best-practices]]
|
||
== Best practices
|
||
|
||
Consider these best practices, whether developing code directly to the {kib} repo or building your own plugins.
|
||
They are intended to support our https://github.com/elastic/engineering/blob/master/kibana_dev_principles.md[{kib} development principals].
|
||
|
||
[discrete]
|
||
=== Performance
|
||
|
||
Are you planning with scalability in mind?
|
||
|
||
* Consider data with many fields
|
||
* Consider data with high cardinality fields
|
||
* Consider large data sets, that span a long time range
|
||
* Are you loading a minimal amount of JS code in the browser?
|
||
** See <<plugin-performance>> for more guidance.
|
||
* Do you make lots of requests to the server?
|
||
** If so, have you considered using the streaming {kib-repo}tree/{branch}/src/plugins/bfetch[bfetch service]?
|
||
|
||
[discrete]
|
||
=== Accessibility
|
||
|
||
Did you know {kib} makes a public statement about our commitment to
|
||
creating an accessible product for people with disabilities?
|
||
https://www.elastic.co/guide/en/kibana/master/accessibility.html[We do]!
|
||
It’s very important all of our apps are accessible.
|
||
|
||
* Learn how https://elastic.github.io/eui/#/guidelines/accessibility[EUI
|
||
tackles accessibility]
|
||
* If you don’t use EUI, follow the same EUI accessibility standards
|
||
|
||
[[kibana-localization-best-practices]]
|
||
[discrete]
|
||
=== Localization
|
||
|
||
{kib} is translated into other languages. Use our i18n utilities to
|
||
ensure your public facing strings will be translated to ensure all
|
||
{kib} apps are localized.
|
||
|
||
* Read and adhere to our
|
||
{kib-repo}blob/{branch}/packages/kbn-i18n/GUIDELINE.md[i18n
|
||
guidelines]
|
||
|
||
[discrete]
|
||
=== Conventions
|
||
|
||
* Become familiar with our
|
||
{kib-repo}blob/{branch}/STYLEGUIDE.md[styleguide]
|
||
(use Typescript!)
|
||
* Write all new code on
|
||
{kib-repo}blob/{branch}/src/core/README.md[the
|
||
platform], and following
|
||
{kib-repo}blob/{branch}/src/core/CONVENTIONS.md[conventions].
|
||
* _Always_ use the `SavedObjectClient` for reading and writing Saved
|
||
Objects.
|
||
* Add `README`s to all your plugins and services.
|
||
* Make your public APIs as small as possible. You will have to maintain
|
||
them, and consider backward compatibility when making any changes to
|
||
them.
|
||
* Use https://elastic.github.io/eui[EUI] for all your basic UI
|
||
components to create a consistent UI experience.
|
||
|
||
[discrete]
|
||
=== Re-inventing the wheel
|
||
|
||
Over-refactoring can be a problem in it’s own right, but it’s still
|
||
important to be aware of the existing services that are out there and
|
||
use them when it makes sense. We have service oriented teams dedicated
|
||
to providing our solution developers the tools needed to iterate faster.
|
||
They take care of the nitty gritty so you can focus on creative
|
||
solutions to your particular problem sphere. Some examples of common
|
||
services you should consider:
|
||
|
||
* {kib-repo}tree/{branch}/src/plugins/data/README.md[Data
|
||
services]
|
||
** {kib-repo}tree/{branch}/src/plugins/data/public/search/README.md[Search
|
||
strategies]
|
||
*** Use the `esSearchStrategy` to make raw queries to ES that will
|
||
support async searching and partial results, as well as injecting the
|
||
right advanced settings like whether to include frozen indices or not.
|
||
* {kib-repo}tree/{branch}/src/plugins/embeddable/README.md[Embeddables]
|
||
** Rendering maps, visualizations, dashboards in your application
|
||
** Register new widgets that will can be added to a dashboard or Canvas
|
||
workpad, or rendered in another plugin.
|
||
* {kib-repo}tree/{branch}/src/plugins/ui_actions/README.md[UiActions]
|
||
** Let other plugins inject functionality into your application
|
||
** Inject custom functionality into other plugins
|
||
* Stateless helper utilities
|
||
* {kib-repo}tree/{branch}/src/plugins/kibana_utils/docs/state_sync/README.md[state
|
||
syncing] and
|
||
* {kib-repo}tree/{branch}/src/plugins/kibana_utils/docs/state_containers/README.md[state
|
||
container] utilities provided by
|
||
* {kib-repo}tree/{branch}/src/plugins/kibana_utils/README.md[kibana_utils]
|
||
if you want to sync your application state to the URL?
|
||
** {kib-repo}tree/{branch}/src/plugins/kibana_react/README.md[kibana_react]
|
||
for react specific helpers
|
||
|
||
Re-using these services will help create a consistent experience across
|
||
{kib} from every solution.
|
||
|
||
[discrete]
|
||
=== Backward compatibility
|
||
|
||
Eventually we want to guarantee to our plugin developers that their plugins will not break from minor to minor.
|
||
|
||
Any time you create or change a public API, keep this in mind, and consider potential
|
||
backward compatibility issues. While we have a formal
|
||
{kib-repo}tree/{branch}/src/core/server/saved_objects/migrations/README.md[saved
|
||
object migration system] and are working on adding a formal state migration system, introducing state changes and migrations in a
|
||
minor always comes with a risk. Consider this before making huge and
|
||
risky changes in minors, _especially_ to saved objects.
|
||
|
||
* Are you persisting state from registries? Consider what will happen if
|
||
the author of the implementation changed their interfaces.
|
||
* Are you adding implementations to registries? Consider that someone
|
||
may be persisting your data, and that making changes to your public
|
||
interfaces can break their code.
|
||
|
||
Be very careful when changing the shape of saved objects or persistable
|
||
data.
|
||
|
||
Saved object exported from past {kib} versions should continue to work.
|
||
In addition, if users are relying on state stored in your app’s URL as
|
||
part of your public contract, keep in mind that you may also need to
|
||
provide backwards compatibility for bookmarked URLs.
|
||
|
||
[discrete]
|
||
=== Routing, Navigation and URL
|
||
|
||
The {kib} platform provides a set of tools to help developers build consistent experience around routing and browser navigation.
|
||
Some of that tooling is inside `core`, some is available as part of various plugins.
|
||
|
||
<<kibana-navigation, Follow this guide>> to get an idea of available tools and common approaches for handling routing and browser navigation.
|
||
|
||
[discrete]
|
||
=== Testing & stability
|
||
|
||
Review:
|
||
|
||
* <<development-unit-tests>>
|
||
* <<stability>>
|
||
* <<security-best-practices>>
|
||
* <<typescript>>
|
||
|
||
include::performance.asciidoc[leveloffset=+1]
|
||
|
||
include::navigation.asciidoc[leveloffset=+1]
|
||
|
||
include::stability.asciidoc[leveloffset=+1]
|
||
|
||
include::security.asciidoc[leveloffset=+1]
|
||
|
||
include::typescript.asciidoc[leveloffset=+1]
|