[8.15] Add dependency docs (#194333) (#194690)

# Backport

This will backport the following commits from `main` to `8.15`:
- [Add dependency docs
(#194333)](#194333)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Larry
Gregory","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-10-02T11:55:32Z","message":"Add
dependency docs (#194333)\n\n## Summary\r\n\r\nAdds and re-organizes
documentation for using third-party
dependencies.","sha":"8e21442caa8e93ab85aed64c102f972985f96ab3","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Security","release_note:skip","v9.0.0","DevDocs","backport:all-open"],"title":"Add
dependency
docs","number":194333,"url":"https://github.com/elastic/kibana/pull/194333","mergeCommit":{"message":"Add
dependency docs (#194333)\n\n## Summary\r\n\r\nAdds and re-organizes
documentation for using third-party
dependencies.","sha":"8e21442caa8e93ab85aed64c102f972985f96ab3"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/194333","number":194333,"mergeCommit":{"message":"Add
dependency docs (#194333)\n\n## Summary\r\n\r\nAdds and re-organizes
documentation for using third-party
dependencies.","sha":"8e21442caa8e93ab85aed64c102f972985f96ab3"}}]}]
BACKPORT-->

Co-authored-by: Larry Gregory <[email protected]>

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 <DocLink id="kibThirdPartyDependencies" text="third-party dependencies guide" /> 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.

dev_docs/contributing/standards.mdx

@@ -17,46 +17,7 @@ Please read and abide by our <DocLink id="kibStyleGuide" text="Style guide" />.
 
 ## 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>
+Please read and abide by our <DocLink id="kibThirdPartyDependencies" text="third-party dependencies guide" />.
 
 ## RESTful HTTP APIs
 

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.
+
+
+<DocCallOut>
+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.
+</DocCallOut>
+
+
+## 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 <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 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**
+
+<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>
+
+## 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.

dev_docs/nav-kibana-dev.docnav.json

@@ -51,6 +51,9 @@
         },
         {
           "id": "kibGitHub"
+        },
+        {
+          "id": "kibThirdPartyDependencies"
         }
       ]
     },
@@ -639,4 +642,4 @@
       ]
     }
   ]
-}
+}