Add a high level overview of the Kibana platform and plugin development.

[stacey-gammon]

Add some very high-level documentation about what the Kibana platform is and how plugins are built on top of it.

Will have a separate PR to add to the nav.

[stacey-gammon]

@elasticmachine merge upstream

[joshdover]

There's some overlap between this new doc and the existing Kibana Plugin API doc.

I think there's good content in both and we should consider combining or remixing this a bit. For instance, I think the section in the existing doc about lifecycles and the basic shape of a plugin class would be helpful context for the section in this new doc about setup, start, and plugin parameters. That said, I think the high-level description in this doc is helpful before jumping into the code like the other doc does.

Thinking about the linear flow here, I think a chronology like this would make sense:

• What is the platform
• What is (and isn't) a plugin
• Anatomy of a plugin
• How plugins interact with each other and Core
• How client-side code interacts with server-side code.

[kobelb]

I don't think it's correct for us to consider all exports or plugin contracts to be part of the platform. There are solution-specific plugins that expose public interfaces that I don't think should be considered part of the platform. When discussing this as part of #71566 we only talked about a subset of plugins and core being moved to be under the platform/ folder.

In my opinion, our code structure needs to be reorganized to properly reflect what we've discussed as being part of the platform because there isn't a clear way to differentiate what we consider to be a platform shared-service from the other solution-specific plugins.

[stacey-gammon]

I don't think it's correct for us to consider all exports or plugin contracts to be part of the platform.

I'm okay with brainstorming better messaging. How would you distinguish between platform code and the entirety of all "shared services"(?), before we have that folder structure that you linked to?

We could say it depends on which team owns the plugin but a) I don't think developers should have to know/care about our team structure (which changes frequently), and b) I don't think that will end up always being true.

Trying to define three types of shared code is more difficult than defining two, and requires more overhead to understand. What is the benefit to a developer in distinguishing between "non-core platform code" and other shared services? Or "core platform" vs "non-core platform" code?

Our plugin structure makes a difference between core and all other shared services by splitting them up into two parameters (core, dependencies). Is it helpful for a developer to distinguish between the services available in the second parameter?

Ideal future brainstorm

Taking a moment to ignore all technical complexities, and think of the ideal situation, I would want to have platform code as the first parameter (generic code that is relevant to every solution) and non-generic, solution/plugin specific shared services in the second. Non-platform shared services can be disabled, while platform services can't.

The technical problem is x-pack platform code can't be part of the first param because it's built as a plugin, but let's pretend we can get around that.

Then let's think about the folder structure. There wouldn't need to be a platform/core folder, just platform.

Then the terminology we could use is:

• platform services
• plugin services
• all shared services (platform + plugins)

If we think this is a good long term direction, I could switch this terminology around to refer to "core platform services" as "platform services", and call "non-core platform services", "plugin services". Perhaps with a caveat that some plugin services are very "platform-y", and will over time, be migrated into the core system. That we use plugin services to test out potential platform services while their APIs are still under frequent iteration, so when we do move them, officially, into the platform, they are somewhat stable.

[stacey-gammon]

Took a stab at giving a more accurate, though slightly more confusing, description of the eco system today.

[kobelb]

I really like the way that you've approached this. I think think the best thing we can do right now is to clearly acknowledge the current state and its deficiencies so we can work on resolving them.

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: a7501e4

Metrics [docs]

✅ unchanged

History

• 💔 Build #99233 failed 9384896
• 💔 Build #99222 failed 02999d6
• 💔 Build #99196 failed 5efde75
• 💔 Build #98951 failed 0964dcd
• 💚 Build #98727 succeeded ce2db93

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

[kibanamachine]

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 87560 or prevent reminders by adding the backport:skip label.

[kibanamachine]

Friendly reminder: Looks like this PR hasn’t been backported yet.
To create backports run node scripts/backport --pr 87560 or prevent reminders by adding the backport:skip label.

[stacey-gammon]

Adding backport skip tag, I backported this doc when I fixed the bad link