From cf22d73a91c9867b0a8ada9b22d442a3b2461341 Mon Sep 17 00:00:00 2001 From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Date: Wed, 2 Oct 2024 22:28:22 +1000 Subject: [PATCH] [8.15] Add dependency docs (#194333) (#194690) # Backport This will backport the following commits from `main` to `8.15`: - [Add dependency docs (#194333)](https://github.com/elastic/kibana/pull/194333) ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) Co-authored-by: Larry Gregory --- dev_docs/contributing/dev_principles.mdx | 2 + dev_docs/contributing/standards.mdx | 41 +--------- .../contributing/third_party_dependencies.mdx | 74 +++++++++++++++++++ dev_docs/nav-kibana-dev.docnav.json | 5 +- 4 files changed, 81 insertions(+), 41 deletions(-) create mode 100644 dev_docs/contributing/third_party_dependencies.mdx diff --git a/dev_docs/contributing/dev_principles.mdx b/dev_docs/contributing/dev_principles.mdx index cbea79e658684..8633352863011 100644 --- a/dev_docs/contributing/dev_principles.mdx +++ b/dev_docs/contributing/dev_principles.mdx @@ -85,6 +85,8 @@ When the use of an external dependency is necessary, ensure there is sufficient Except in specific cases where widespread consensus was gained and clear ownership is established, third party dependencies should not be exposed directly as features of Kibana, whether it be through the UI, HTTP API, or programmatic interfaces. +See the for more information. + ## Don't share code prematurely There are many modules throughout Kibana's codebase where we have generic utilities that seem appropriate for use elsewhere in the codebase, but doing so is creating another public interface which has a cost in terms of maintenance, testing, documentation, and complexity that increases with each usage. Over the long term, shared utilities tend to accumulate additional complexity in order to be flexible enough for the various use cases of its consumers, particularly when they are shared across domain/plugin boundaries. diff --git a/dev_docs/contributing/standards.mdx b/dev_docs/contributing/standards.mdx index 80df5f4752131..bb63eda578451 100644 --- a/dev_docs/contributing/standards.mdx +++ b/dev_docs/contributing/standards.mdx @@ -17,46 +17,7 @@ Please read and abide by our . ## 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 . 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** - - - 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). - +Please read and abide by our . ## RESTful HTTP APIs diff --git a/dev_docs/contributing/third_party_dependencies.mdx b/dev_docs/contributing/third_party_dependencies.mdx new file mode 100644 index 0000000000000..ea8eb9cd154a9 --- /dev/null +++ b/dev_docs/contributing/third_party_dependencies.mdx @@ -0,0 +1,74 @@ +--- +id: kibThirdPartyDependencies +slug: /kibana-dev-docs/third-party-dependencies +title: Managing third-party dependencies +description: Expectations for working with third-party dependencies +date: 2024-10-01 +tags: ['contributor', 'dev', 'kibana', 'npm', 'dependencies', 'third-party', 'dependency'] +--- + +## Third-party dependencies + +Third-party dependencies allow us to leverage the broader web development community to effeciently bring ideas to life, without having to re-invent the wheel. +This is an attractive proposition, but using someone else's code does not absolve us of responsibility. + +The Kibana project is not just the code we commit to the repo but rather the combined total of all of the source code from our own repo and all of the external dependencies we rely on. When a user encounters a deficiency in Kibana, it matters not whether the root cause is in code we've written or external code we depend on. Additionally, relying on a dependency is a considerable expense in terms of cognitive burden, maintenance overhead, and risk. + +Except for highly specialized functionality, dependencies often do more harm in the long term than their short term benefits justify. Always be critical of new external dependencies being added to the project, and frequently re-evaluate the use of existing dependencies. + +When the use of an external dependency is necessary, ensure there is sufficient integration testing in Kibana to ensure it continues to operate the way we'd expect when we change the consuming code in Kibana or upgrade the dependency code. + +Except in specific cases where widespread consensus was gained and clear ownership is established, third party dependencies should not be exposed directly as features of Kibana, whether it be through the UI, HTTP API, or programmatic interfaces. + + + +Treat third-party code as if it was your own. We share the responsibility for the efficacy, performance, and security of both the code we integrate and the code we develop. + + + +## Adding new 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 . 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 are only supported for development (`devDependencies`), and are not supported for production (`dependencies`). +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 (and will soon require) 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** + + + 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). + + +## Using existing dependencies + +Using an existing dependency is typically preferred over adding a new one. +Please consult with the owning team before using an existing dependency, as they may have specific guidelines or concerns about its use. diff --git a/dev_docs/nav-kibana-dev.docnav.json b/dev_docs/nav-kibana-dev.docnav.json index 26b955c1c7c55..5d5052d6d0740 100644 --- a/dev_docs/nav-kibana-dev.docnav.json +++ b/dev_docs/nav-kibana-dev.docnav.json @@ -51,6 +51,9 @@ }, { "id": "kibGitHub" + }, + { + "id": "kibThirdPartyDependencies" } ] }, @@ -639,4 +642,4 @@ ] } ] -} +} \ No newline at end of file