From 3c71ead22e7668d826fbf4c7c024cb1de4b625ba Mon Sep 17 00:00:00 2001
From: Marc Pichler <marc.pichler@dynatrace.com>
Date: Thu, 13 Jun 2024 13:49:13 +0200
Subject: [PATCH] docs: add contributing guidelines for new instrumentations
 (#2259)

* docs: add contributing guidelines for new instrumentations

* Update CONTRIBUTING.md

Co-authored-by: Jamie Danielson <jamieedanielson@gmail.com>

---------

Co-authored-by: Jamie Danielson <jamieedanielson@gmail.com>
---
 ..._request.md => instrumentation_request.md} | 13 ++++++--
 CONTRIBUTING.md                               | 33 +++++++++++++++++++
 README.md                                     |  1 +
 3 files changed, 44 insertions(+), 3 deletions(-)
 rename .github/ISSUE_TEMPLATE/{plugin_request.md => instrumentation_request.md} (65%)

diff --git a/.github/ISSUE_TEMPLATE/plugin_request.md b/.github/ISSUE_TEMPLATE/instrumentation_request.md
similarity index 65%
rename from .github/ISSUE_TEMPLATE/plugin_request.md
rename to .github/ISSUE_TEMPLATE/instrumentation_request.md
index 2f588b9759..408e111f7f 100644
--- a/.github/ISSUE_TEMPLATE/plugin_request.md
+++ b/.github/ISSUE_TEMPLATE/instrumentation_request.md
@@ -5,9 +5,7 @@ labels: instrumentation-request
 ---
 
 <!--
-**NB:** Before opening an instrumentation request against this repo, consider whether the instrumentation should/could be implemented in the [other OpenTelemetry client libraries](https://github.com/open-telemetry/). If so, please [open an issue on opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification/issues/new) first.
-
-You are welcome to try to build your own instrumentation. If you do, please let us know if you have any questions/feedback.
+**NB:** Before opening an instrumentation request against this repo, please read [the contributing guidelines for new instrumentation](../../CONTRIBUTING.md#new-instrumentation).
 -->
 
 ### Is your instrumentation request related to a problem? Please describe
@@ -27,6 +25,15 @@ Weekly Downloads:
 
 Versions:
 
+### Code Owners
+
+<!--
+New Instrumentation requests need at least 2 code-owners that will maintain the instrumentation long-term.
+-->
+
+- Owner 1
+- Owner 2
+
 ### Additional context
 <!--
 Add any other context or screenshots about the instrumentation request here. Is there a reference you could point for the well-defined lifecycle methods?
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6e014f3ee1..e3441af5ab 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -26,6 +26,7 @@ We'd love your help!
 - [Contributing Vendor Components](#contributing-vendor-components)
   - [Adding a New Vendor Component](#adding-a-new-vendor-component)
   - [Removing Vendor Components](#removing-vendor-components)
+- [New Instrumentation](#new-instrumentation)
 
 ## Development Quick Start
 
@@ -232,6 +233,38 @@ please ping ([@open-telemetry/javascript-approvers](https://github.com/orgs/open
 - New or changed functionality is documented if appropriate
 - Substantial changes should not be merged within 24 hours of opening in order to allow reviewers from all time zones to have a chance to review
 
+## New Instrumentation
+
+**Do not submit pull requests for new instrumentation without reading the following.**
+
+This project is dedicated to promoting the development of quality instrumentation using OpenTelemetry.
+To achieve this goal, we recognize that the instrumentation needs to be written using the best practices of OpenTelemetry, but also by developers that understand the package they are instrumenting.
+Additionally, the produced instrumentation needs to be maintained and evolved.
+
+The size of the OpenTelemetry JavaScript developer community is not large enough to support an ever-growing amount of instrumentation.
+Therefore, to reach our goal, we have the following recommendations for where instrumentation packages should live.
+
+1. Native to the instrumented package
+2. A dedicated public repository
+3. Here in the opentelemetry-js-contrib repository
+
+If possible, OpenTelemetry instrumentation should be included in the instrumented package.
+This will ensure the instrumentation reaches all package users, and is continuously maintained by developers that understand the package.
+
+If instrumentation cannot be directly included in the package it is instrumenting, it should be hosted in a dedicated public repository owned by its maintainer(s).
+This will appropriately assign maintenance responsibilities for the instrumentation and ensure these maintainers have the needed privilege to maintain the code.
+
+The last place instrumentation should be hosted is here in this repository.
+Maintaining instrumentation here hampers the development of OpenTelemetry for JavaScript and therefore should be avoided.
+When instrumentation cannot be included in a target package and there is good reason to not host it in a separate and dedicated repository an [instrumentation request](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/new/choose) should be filed.
+Note that new instrumentation needs at least two contributors assigned to it as code-owners.  It is the responsibility
+of the requesting party to reach out and find code-owners for the proposed instrumentation. The instrumentation request
+needs to be accepted before any pull requests for the instrumentation can be considered for merging.
+
+Regardless of where instrumentation is hosted, it needs to be discoverable.
+The [OpenTelemetry registry](https://opentelemetry.io/registry/) exists to ensure that instrumentation is discoverable.
+You can find out how to add instrumentation to the registry [here](https://github.com/open-telemetry/opentelemetry.io#adding-a-project-to-the-opentelemetry-registry).
+
 ## Contributing Vendor Components
 
 This repo is generally meant for hosting components that work with popular open-source frameworks and tools. However, it is also possible to contribute components specific to a 3rd party vendor in this repo.
diff --git a/README.md b/README.md
index 7dede8487a..5a30f19bf6 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,7 @@ This project includes:
 - [Resource Detectors](./detectors).
 
 **Instrumentations**: OpenTelemetry can collect tracing data automatically using instrumentations. Vendors/Users can also create and use their own.
+Please read the [contributing guidelines on adding new instrumentation](CONTRIBUTING.md#new-instrumentation) before opening any PRs.
 
 **Resource Detectors**: OpenTelemetry can collect resource attributes of the entity that producing telemetry. For example, a process producing telemetry that is running in a container on Kubernetes has a Pod name, it is in a namespace and possibly is part of a Deployment which also has a name. All three of these attributes can be included in the `Resource`.