mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 10:40:07 -04:00
2e38daf343
While reading [Kibana developer guide](https://docs-elastic-dev-staging.vercel.app/kibana-dev-docs/contributing/repo-structure#srcdev) I found ``` Maintained by the Operations team, this code contains build and development tooling related code. This folder existed before `packages`, so contains mostly older code that hasn't been migrated to packages. Prefer creating a `package` if possible. Can be ignored for the most part if you are not on the Ops team. Prefer ``` Also in [Standards and guidelines](https://docs-elastic-dev-staging.vercel.app/kibana-dev-docs/standards#backward-compatibility-and-breaking-changes) the table formatting is off <img width="879" alt="image" src="https://user-images.githubusercontent.com/1313018/236801728-06a6f1e9-2d20-4a91-addb-83c918cf45dc.png">
126 lines
8.8 KiB
Text
126 lines
8.8 KiB
Text
---
|
||
id: kibStandards
|
||
slug: /kibana-dev-docs/standards
|
||
title: Standards and guidelines
|
||
description: Standards and guidelines we expect every Kibana developer to abide by
|
||
date: 2021-09-28
|
||
tags: ['contributor', 'dev', 'github', 'getting started', 'onboarding', 'kibana']
|
||
---
|
||
|
||
## Developer principles
|
||
|
||
We expect all developers to read and abide by our overarching <DocLink id="kibDevPrinciples" />.
|
||
|
||
## Style guide
|
||
|
||
Please read and abide by our <DocLink id="kibStyleGuide" text="Style guide" />. The majority of these items are linted against but some are not.
|
||
|
||
## Adding dependencies
|
||
|
||
Looking for a dependency that isn't already available in Kibana? There are a few things to keep in mind before adding a new dependency.
|
||
|
||
First, be sure you have read and are familiar with our <DocLink id="kibDevPrinciples" />. In particular, **Be wary of dependencies**
|
||
and **Prefer one way to do things** provide an overview of how we approach this question.
|
||
|
||
In general, we have a bias toward **not** adding new dependencies unless there is a compelling reason to do so, as we want to
|
||
minimize Kibana's overall complexity.
|
||
|
||
Should you find yourself evaluating a new dependency, here are some specific things to ask yourself:
|
||
|
||
1. **Is there already another dependency that offers similar functionality?** If so, adding a new dependency may not be necessary.
|
||
Prefer one way to do things and use what's already there, unless there is an important reason not to do so.
|
||
2. **Does this dependency appear to be well-maintained?** A dependency that hasn't been updated in years is usually more of a
|
||
liability than an asset. Make sure the depedency has recent activity, that bugs and security vulnerabilities appear to be addressed
|
||
in a timely manner, and that there is active participation from the maintainers and community.
|
||
3. **How large is the dependency?** For client-side plugins, heavy dependencies can have a real impact on user experience,
|
||
especially if they are included in the initial page bundle and not loaded asynchronously. In some cases it might make more sense
|
||
to roll your own rather than include a bloated depedency, especially if you are only using a single piece of functionality.
|
||
4. **Does this dependency have a license that's compatible with Kibana's?** Most common open source licenses such as BSD, MIT,
|
||
and Apache 2.0/1.1 are okay to use with Kibana. Others may not be, or may require special attribution.
|
||
5. **Will this dependency need to be prebuilt?** Due to our build process, native module dependencies should include at least a prebuild
|
||
step so at install time it simply downloads instead of building from source. This allows us to optimize bootstrap times.
|
||
6. **Am I committed to maintaining this dependency?** Once you add a dependency to the `package.json`, someone else isn't going to
|
||
keep it updated for you. That means you will be responsible for updating it regularly, keeping an eye out for security vulnerabilities,
|
||
and dealing with any breaking changes that may arise during an upgrade. We recommend relying on the renovate bot to help keep the
|
||
dependency updated; be sure to mark your ownership of the package in the
|
||
[`renovate.json`](https://github.com/elastic/kibana/blob/main/renovate.json`) file.
|
||
|
||
If you have any questions about whether adding a dependency is appropriate, feel free to reach out to one of the following teams
|
||
on Github:
|
||
|
||
- **@elastic/kibana-tech-leads**
|
||
- **@elastic/kibana-core**
|
||
- **@elastic/kibana-operations**
|
||
- **@elastic/kibana-security**
|
||
|
||
<DocCallOut title="Internal only">
|
||
If you are unsure of which licenses are okay to use, refer to the
|
||
[Permitted Open Source Licenses list](https://github.com/elastic/open-source/blob/main/elastic-product-policy.md#permitted-licenses-list).
|
||
</DocCallOut>
|
||
|
||
## RESTful HTTP APIs
|
||
|
||
### Terminology
|
||
|
||
**REST APIs**
|
||
Technically, REST does not specify a protocol, but for readability, we’ll be calling RESTful HTTP APIs as REST APIs for short for the remainder of the section. HTTP APIs that serve HTML, CSS and images are not REST APIs.
|
||
|
||
**End user**
|
||
Anywhere we refer to “end user” in this section, we are referring to someone who is using the REST APIs. The distinction between Product breaking changes and plugin breaking changes can also be found in this [Make it Minor strawman proposal doc](https://docs.google.com/document/d/12R0w75dSNR-VDQLGl2vxFyEHhzxNT38iamYhven9uvw/edit). This can be a tricky distinction, as some folks may consider end user to only be folks that use the Kibana UI.
|
||
|
||
### Privacy
|
||
|
||
| Type | Description | Guarantees |
|
||
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
||
| Internal | An API with “internal” in the route. Specifically it should be `/internal/{pluginname}/{...}`. It should only be used by the plugin that created it. | None |
|
||
| Public | Any API that is not internal based on above definition | Based on <DocLink id="kibStandards" section="release-tags" text="release tag"/> |
|
||
|
||
### Do not access directly from plugins
|
||
|
||
Plugins should not attempt to directly access the REST APIs created by another plugin. The plugin author who registered the public REST API should provide access to it via functionality on the plugin lifecycle contract. Accessing functionality through a client side plugin contract provides more type-safety compared to calling the REST API directly. Never attempt to call a server-side REST API if you are already on the server-side. It will not work. This should also be avoided in any code provided within a common folder.
|
||
|
||
### Path names
|
||
|
||
All public API path names should start with `/api/`.
|
||
All internal APIs should start with `/internal/{pluginname}/{...}`.
|
||
|
||
### Backward compatibility and breaking changes
|
||
|
||
Every public API should have a release tag specified at the top of it’s documentation page. Release tags are not applicable to internal APIs, as we make no guarantees on those.
|
||
|
||
#### Release tags
|
||
|
||
| Type | Description | Documentation | Asciidoc Tag |
|
||
| -----| ------------| ------------- | ------------ |
|
||
| Undocumented | Every public API should be documented, but if it isn’t, we make no guarantees about it. These need to be eliminated and should become internal or documented. | | |
|
||
| Experimental | A public API that may break or be removed at any time. | experimental[] | |
|
||
| Beta | A public API that we make a best effort not to break or remove. However, there are no guarantees. | beta[] | |
|
||
| Stable | No breaking changes outside of a Major\* | stable[] | |
|
||
| Deprecated | Do not use, will be removed. | deprecated[] | |
|
||
|
||
\*This is likely to change with Make it Minor as we move towards a calendar based rolling deprecation and removal policy.
|
||
|
||
#### What constitutes a breaking change?
|
||
|
||
- A path change
|
||
- A request payload change that adds a new required variable, or changes an existing one (new optional parameters are not breaking).
|
||
- A response payload change that removes data or changes existing data (returning additional data is not breaking).
|
||
- Status code changes
|
||
|
||
### Telemetry
|
||
|
||
Every team should be collecting telemetry metrics on it’s public API usage. This will be important for knowing when it’s safe to make breaking changes. The Core team will be looking into ways to make this easier and an automatic part of registration (see [#112291](https://github.com/elastic/kibana/issues/112291)).
|
||
|
||
### APM
|
||
|
||
Kibana server and client are instrumented with APM node and APM RUM clients respectively, tracking several types of transactions by default, such as `page-load`, `request`, etc.
|
||
You may introduce custom transactions. Please refer to the [APM documentation](https://www.elastic.co/guide/en/apm/get-started/current/index.html) and follow these guidelines when doing so:
|
||
|
||
- Use dashed syntax for transaction types and names: `my-transaction-type` and `my-transaction-name`
|
||
- [Refrain from adding too many custom labels](https://www.elastic.co/guide/en/apm/get-started/current/metadata.html)
|
||
|
||
### Documentation
|
||
|
||
Every public API should be documented inside the [docs/api](https://github.com/elastic/kibana/tree/main/docs/api) folder in asciidoc (this content will eventually be migrated to mdx to support the new docs system). If a public REST API is undocumented, you should either document it, or make it internal.
|
||
|
||
Every public API should have a release tag specified using the appropriate documentation release tag above. If you do this, the docs system will provide a pop up explaining the conditions. If an API is not marked, it should be considered experimental.
|