From 088a0069db0099c82168154170481cc83f418507 Mon Sep 17 00:00:00 2001 From: restrry Date: Thu, 12 Mar 2020 11:42:55 +0100 Subject: [PATCH 1/5] add platform team definition of done --- src/core/CONVENTIONS.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index 0f592d108c561..9eccee6ae3c9e 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -1,6 +1,5 @@ -# Kibana Conventions - -- [Kibana Conventions](#kibana-conventions) +- [Organisational Conventions](#organisational-conventions) +- [Technical Conventions](#technical-conventions) - [Plugin Structure](#plugin-structure) - [The PluginInitializer](#the-plugininitializer) - [The Plugin class](#the-plugin-class) @@ -8,8 +7,26 @@ - [Services](#services) - [Usage Collection](#usage-collection) - [Saved Objects Types](#saved-objects-types) - -## Plugin Structure + - [Naming conventions](#naming-conventions) + +## Organisational Conventions +### Definition of done +Definition of done for a feature: +- has a dedicated Github issue describing problem space +- an umbrella task closed/updated with follow-ups +- all code review comments are resolved +- works for OSS version +- works for the commercial version with a license + - for a logged-in user + - for anonymous user + - compatible with Spaces +- can be used by the first & third party plugins +- has unit & integration tests for public contracts +- has functional tests for user scenarios +- has documentation for the public contract, provides a usage example + +## Technical Conventions +### Plugin Structure All Kibana plugins built at Elastic should follow the same structure. @@ -60,7 +77,7 @@ my_plugin/ - More should be fleshed out here... - Usage collectors for Telemetry should be defined in a separate `server/collectors/` directory. -### The PluginInitializer +#### The PluginInitializer ```ts // my_plugin/public/index.ts @@ -75,7 +92,7 @@ export { } ``` -### The Plugin class +#### The Plugin class ```ts // my_plugin/public/plugin.ts @@ -130,7 +147,7 @@ Difference between `setup` and `start`: The bulk of your plugin logic will most likely live inside _handlers_ registered during `setup`. -### Applications +#### Applications It's important that UI code is not included in the main bundle for your plugin. Our webpack configuration supports dynamic async imports to split out imports into a separate bundle. Every app's rendering logic and UI code should @@ -175,7 +192,7 @@ export class MyPlugin implements Plugin { } ``` -### Services +#### Services Service structure should mirror the plugin lifecycle to make reasoning about how the service is executed more clear. @@ -226,7 +243,7 @@ export class Plugin { } ``` -### Usage Collection +#### Usage Collection For creating and registering a Usage Collector. Collectors should be defined in a separate directory `server/collectors/`. You can read more about usage collectors on `src/plugins/usage_collection/README.md`. @@ -263,7 +280,7 @@ export function registerMyPluginUsageCollector(usageCollection?: UsageCollection } ``` -### Saved Objects Types +#### Saved Objects Types Saved object type definitions should be defined in their own `server/saved_objects` directory. From b041d0056f526d91995e2f703b59390d1e9a3301 Mon Sep 17 00:00:00 2001 From: restrry Date: Thu, 12 Mar 2020 11:48:51 +0100 Subject: [PATCH 2/5] add link to ToC --- src/core/CONVENTIONS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index 9eccee6ae3c9e..a62904131f85c 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -1,4 +1,5 @@ - [Organisational Conventions](#organisational-conventions) + - [Definition of done](#definition-of-done) - [Technical Conventions](#technical-conventions) - [Plugin Structure](#plugin-structure) - [The PluginInitializer](#the-plugininitializer) From a65bb87198426bb0b46cdc9f77254ecc4ae30bbd Mon Sep 17 00:00:00 2001 From: restrry Date: Thu, 19 Mar 2020 11:24:31 +0100 Subject: [PATCH 3/5] add suggestions from Josh --- src/core/CONVENTIONS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index a62904131f85c..295813c594c81 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -17,6 +17,8 @@ Definition of done for a feature: - an umbrella task closed/updated with follow-ups - all code review comments are resolved - works for OSS version + - works with and without a `server.basePath` configured + - cannot crash the Kibana server when it fails - works for the commercial version with a license - for a logged-in user - for anonymous user From 1ccac27fa42b0857980fede0c6d923ed698fc8d3 Mon Sep 17 00:00:00 2001 From: restrry Date: Tue, 24 Mar 2020 10:34:06 +0100 Subject: [PATCH 4/5] add tooling --- src/core/CONVENTIONS.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index 295813c594c81..0a325be8b2937 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -16,6 +16,8 @@ Definition of done for a feature: - has a dedicated Github issue describing problem space - an umbrella task closed/updated with follow-ups - all code review comments are resolved +- can be used by first & third party plugins +- there is no contradiction between client and server API - works for OSS version - works with and without a `server.basePath` configured - cannot crash the Kibana server when it fails @@ -23,9 +25,12 @@ Definition of done for a feature: - for a logged-in user - for anonymous user - compatible with Spaces -- can be used by the first & third party plugins - has unit & integration tests for public contracts - has functional tests for user scenarios +- uses standard tooling: + - code - `TypeScript` + - UI - `React` + - tests - `jest` & `FTR` - has documentation for the public contract, provides a usage example ## Technical Conventions From 24f08d8dabe66f0486169dad84cb12bd2b542034 Mon Sep 17 00:00:00 2001 From: restrry Date: Wed, 15 Apr 2020 17:01:11 +0200 Subject: [PATCH 5/5] add testing note --- src/core/CONVENTIONS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/core/CONVENTIONS.md b/src/core/CONVENTIONS.md index 0a325be8b2937..a82cc27839a1d 100644 --- a/src/core/CONVENTIONS.md +++ b/src/core/CONVENTIONS.md @@ -16,6 +16,7 @@ Definition of done for a feature: - has a dedicated Github issue describing problem space - an umbrella task closed/updated with follow-ups - all code review comments are resolved +- has been verified manually by at least one reviewer - can be used by first & third party plugins - there is no contradiction between client and server API - works for OSS version