dev_docs/contributing/code_walkthrough.mdx
A high-level walk through of the folder structure of our repository.
Tip: Look for a README.md in a folder to learn about its contents.
Managed by the operations team to set up a new buildkite ci system. Can be ignored by folks outside the Operations team.
Contains GitHub configuration settings. This file contains issue templates, and the CODEOWNERS file. It's important for teams to keep the CODEOWNERS file up-to-date so the right team is pinged for a code owner review on PRs that edit certain files. Note that the CODEOWNERS file only exists on the main branch, and is not backported to other branches in the repo. To aid in making sure the CODEOWNERS file is always up-to-date "packages" in the Kibana repo are required to have an "owner" defined, those owners are then injected into the CODEOWNERS files automatically by the node scripts/generate codeowners command.
Every file in here is auto-generated by the <DocLink id="kibDevDocsApiWelcome" text="API Docs system"/> and used to render our API documentation. If you edit a public plugin or package API and run node scripts/build_api_docs you will see files changed in this folder. Do not edit the contents of this folder directly!
Note that currently you may see a lot of changes because that command is not run on every PR and so the content in this folder is often outdated.
This contains the base configuration file, kibana.yml. If you want to tweak any settings, create a kibana.dev.yml in here which will get picked up during development, and not checked into GitHub.
Every folder in here except the development one contains manually generated asciidocs that end up hosted in our Elastic guide.
The development folder contains markdown that is auto-generated with our legacy API docs tool. We are aiming to remove it shortly after 8.0FF.
This is where a lot of manually written content for our Developer Guide resides. Developers may also keep the information closer to what it's describing, but it's a good spot for high-level information, or information that describes how multiple plugins work together.
These are our tested example plugins that also get built and hosted here. If a plugin is written for testing purposes only, it won't go in here. These example plugins should be written with the intention of helping developers understand how to use our services.
We used to write RFCs in md format and keep them in the repository, but we have since moved to Google Docs. We kept the folder around, since some folks still read these old docs. If you are an internal contributor you can visit <DocLink id="ktRFCProcess" text="this document"/> to read about our current RFC process.
Contains our two license header texts, one for the Elastic license and one for the Elastic+SSPL license. All code files inside x-pack should have the Elastic license text at the top, all code files outside x-pack should contain the other. If you have your environment set up to auto-fix on save, eslint should take care of adding it for you. If you don't have it, ci will fail. Can be ignored for the most part, this rarely changes.
This is an empty folder in GitHub. It's where third party developers should put their plugin folders. Internal developers can ignore this folder.
Contains a bunch of developer scripts. These are usually very small files with just two lines that kick off a command, the logic of which resides elsewhere (sometimes src/dev, sometimes inside packages).
Example:
require('../src/setup_node_env');
require('@kbn/es-archiver').runCli();
This folder and the packages folder contain the most code and where developers usually find themselves. I'll touch on a few of the subfolder, the rest can generally be ignored, or are build/ops related code.
Maintained primarily by the Operations team, this folder contains code that initializes the Kibana runtime and a bit of work to handle authorization for interactive setup mode. Most devs should be able to ignore this code.
This code primarily belongs to the Core team and contains the plugin infrastructure, as well as a bunch of fundamental services like migrations, saved objects, and some UI utilities (toasts, flyouts, etc.).
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.
Contains the Basic-licensed code that is common to all Kibana solutions. The code is organised in modules, that can be either plugins or packages. <DocLink id="kibPlatformIntro" section="1000-foot-view" text="This document"/> covers how packages differ from plugins.
Contains Basic-licensed plugins that are common to all Kibana solutions. They are organized according to their visibility: Thy can be shared or private (aka not accessible from solutions).
Contains functional tests and related FTR (functional test runner) code for the plugins inside src/plugins, although there is a push to move the tests to reside inside the plugins themselves.
Maintained by Ops and Core, this contains global typings for dependencies that do not provide their own types, or don't have types available via DefinitelyTyped. This directory is intended to be minimal; types should only be added here as a last resort.
Contains all code and infrastructure that powers our gold+ (non-basic) features that are provided under a more restrictive license. The code is organized in the following subfolders:
Contains all of the gold+ (non-basic) modules that are common to all Kibana solutions. Like the src/platform code, it is organized in modules that can be either plugins or packages, and in turn, these plugins are organized according to their visibility.
Contains all of the code that is specific to each Kibana solution. At the moment, we have a folder for observability, another for security, another for search and another for workplaceai (serverless only).
These folders contain the modules that belong to each solution, and these modules are also categorised as plugins or packages.
Unlike the src/platform and the x-pack/platform code, the solution-specific modules are private by definition, aka they cannot be accessed from platform nor from other solutions.
Maintained by the App Services UX team, this contains Reporting-related code for building Chromium in order to take server side screenshots.
Maintained by the Operations team.
Contains all example plugins that rely on gold+ features.
Contains code for all the plugins that power our gold+ features.
Maintained by the Ops team, this folder contains some scripts for running x-pack utilities, like the functional test runner that runs with a license higher than Basic.
Functional tests for our gold+ features.