docs: document component maturity levels (open-telemetry#1474)

* docs: document component maturity levels

* docs: link maturity levels from README

* Typo

Co-authored-by: Marc Pichler <[email protected]>

* Link header instead of owner

---------

Co-authored-by: Marc Pichler <[email protected]>

Author: dyladan

.github/component_owners.yml

@@ -4,7 +4,7 @@ components:
     - legendecas
   detectors/node/opentelemetry-resource-detector-aws:
     - carolabadeer
-  detectors/node/opentelemetry-resource-detector-docker:
+  detectors/node/opentelemetry-resource-detector-container:
     - abhee11
   detectors/node/opentelemetry-resource-detector-instana:
     - basti1302

CONTRIBUTING.md

@@ -2,6 +2,27 @@
 
 We'd love your help!
 
+- [Report a bug or requesting feature](#report-a-bug-or-requesting-feature)
+- [How to contribute](#how-to-contribute)
+  - [Before you start](#before-you-start)
+    - [Conventional commit](#conventional-commit)
+  - [Fork](#fork)
+  - [Running the tests](#running-the-tests)
+  - [Generating API documentation](#generating-api-documentation)
+  - [Generating CHANGELOG documentation](#generating-changelog-documentation)
+  - [Benchmarks](#benchmarks)
+- [Component Ownership](#component-ownership)
+- [Component Lifecycle](#component-lifecycle)
+  - [Unreleased](#unreleased)
+  - [Experimental](#experimental)
+  - [Beta](#beta)
+  - [Stable](#stable)
+  - [Unmaintained](#unmaintained)
+  - [Deprecated](#deprecated)
+- [Contributing Vendor Components](#contributing-vendor-components)
+  - [Adding a New Vendor Component](#adding-a-new-vendor-component)
+  - [Removing Vendor Components](#removing-vendor-components)
+
 ## Report a bug or requesting feature
 
 Reporting bugs is an important contribution. Please make sure to include:
@@ -80,6 +101,67 @@ When two or more approaches must be compared, please write a benchmark in the be
 
 - `npm run bench` to run your benchmark.
 
+## Component Ownership
+
+This repository contains many components which are maintained by more than the typical set of JS maintainers and approvers.
+Each component in this repository SHOULD have a component owner who is responsible for maintaining it.
+The README.md for each component SHOULD contain its owner, but the source of truth for component ownership is in [.github/component_owners.yml](.github/component_owners.yml).
+Component owners are generally given authority to make decisions relating to implementation and feature requests for their components, provided they follow the best practices set out by the maintainers.
+Component owners MUST do their best to maintain a high level of quality, security, performance, and specification compliance within their components.
+Maintainers may override the decisions of component owners, but should only do so when they feel one or more of these traits is compromised.
+
+## Component Lifecycle
+
+This repository contains many components in various stages of the component lifecycle.
+A component may be **unreleased**, **experimental**, **beta**, **stable**, **unmaintained**, or **deprecated**; see the below definitions for each stability level.
+With the exception of the stable status, it is up to each individual [component owner](#component-ownership) to determine the status of a component.
+A component may only be marked stable with the approval of a member of @open-telemetry/javascript-maintainers; see the definition of stable below for more details.
+
+### Unreleased
+
+Unreleased components are in active development and have not yet been released to NPM.
+Unreleased packages should have the property `private` in their `package.json` set to `true`.
+
+### Experimental
+
+Experimental packages are in active development.
+They should be considered unstable and potentially unsuitable for production use.
+They are released to NPM for developers and early adopters.
+Experimental components MUST have their major version set to `0`.
+If a component does not have an explicit status in its README.md file, it should be considered to be experimental.
+
+### Beta
+
+Beta packages are not yet considered stable, but an effort should be made to preserve stability across versions if possible.
+They may be ready for production use, but users should understand that their APIs or the telemetry they output MAY change if required.
+Beta components MUST have their major version set to `0`.
+
+### Stable
+
+This is the highest level of quality and maintainership guarantee provided in this repository.
+Stable packages should be considered stable and ready for production use.
+In order for a package to be marked stable, it must meet the following requirements:
+
+- It MUST have a component owner that the JS maintainers feel confident will be responsive to issues and pull requests and will fulfill their responsibility competently.
+  If a component owner is not responsive to issues and PRs, the maintainers may assign a new owner or change the status of the component to unmaintained.
+- All relevant specification relating to the component MUST be stable. For example, telemetry emitted by an instrumentation library should rely on a stable semantic convention.
+- It MUST be reviewed and approved by a member of @open-telemetry/javascript-maintainers.
+
+Stable components MUST have their major version set to `1` or greater.
+
+### Unmaintained
+
+A component which does not have an assigned component owner, or has a component owner who has been unresponsive to issues and pull requests may be marked as unmaintained.
+Unmaintained components may continue to work and receive updates and fixes from contributors, but may not receive immediate attention if there is a problem or feature request.
+A component which is unmaintained may be deprecated if there is a problem that is not fixed in a timely manner.
+
+### Deprecated
+
+Deprecated components are no longer maintained and there are not currently plans to maintain them.
+They may not work and there are no guarantees for fixes or new features.
+Their source files may be deleted from the repository.
+Any packages released from their source will be marked as deprecated in NPM.
+
 ## 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.

README.md

@@ -51,6 +51,10 @@ This project includes:
 
 **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`.
 
+## Stability levels
+
+Stability level for components in this repository follow the definitions in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Supported Runtimes
 
 Packages in this repository have a variable range of support for Node.JS and browser versions which for each package depend on

detectors/node/opentelemetry-resource-detector-aws/README.md

@@ -7,7 +7,11 @@
 
 Resource detector for Amazon Web Services.
 
-Compatible with OpenTelemetry JS API and SDK `1.0+`.
+## Status
+
+| Maturity                                  | [Component Owner](../../.github/component_owners.yml) | Compatibility         |
+| ----------------------------------------- | ----------------------------------------------------- | --------------------- |
+| [Stable](../../../CONTRIBUTING.md#stable) | @carolabadeer                                         | API 1.0+<br/>SDK 1.0+ |
 
 ## Installation
 

packages/opentelemetry-id-generator-aws-xray/README.md

@@ -3,20 +3,22 @@
 [![NPM Published Version][npm-img]][npm-url]
 [![Apache License][license-image]][license-image]
 
-[component owners](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/.github/component_owners.yml): @carolabadeer
-
 The OpenTelemetry IdGenerator for AWS X-Ray generates trace IDs with its first four bytes set to the start time of the
 trace followed by a unique identifier consisting of 12 bytes of randomly generated numbers. OpenTelemetry offers an
 extension point which allows the usage of this custom IdGenerator as opposed to the out-of-the-box random IdGenerator,
 enabling compatibility with AWS X-Ray.
 
-Compatible with OpenTelemetry JS API and SDK `1.0+`.
+## Status
+
+| Maturity                               | [Component Owner](../../.github/component_owners.yml) | Compatibility         |
+| -------------------------------------- | ----------------------------------------------------- | --------------------- |
+| [Stable](../../CONTRIBUTING.md#stable) | @carolabadeer                                         | API 1.0+<br/>SDK 1.0+ |
 
 ## Installation
 
-`
+```bash
 npm install --save @opentelemetry/id-generator-aws-xray
-`
+```
 
 ## Usage
 

propagators/opentelemetry-propagator-aws-xray/README.md

@@ -3,13 +3,15 @@
 [![NPM Published Version][npm-img]][npm-url]
 [![Apache License][license-image]][license-image]
 
-[component owners](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/.github/component_owners.yml): @carolabadeer
-
 The OpenTelemetry Propagator for AWS X-Ray provides HTTP header propagation for systems that are using AWS `X-Amzn-Trace-Id` format.
 This propagator translates the OpenTelemetry SpanContext into the equivalent AWS header format, for use with the OpenTelemetry JS SDK.
 `TraceState` is currently not propagated.
 
-Compatible with OpenTelemetry JS API and SDK `1.0+`.
+## Status
+
+| Maturity                                  | [Component Owner](../../.github/component_owners.yml) | Compatibility         |
+| ----------------------------------------- | ----------------------------------------------------- | --------------------- |
+| [Stable](../../../CONTRIBUTING.md#stable) | @carolabadeer                                         | API 1.0+<br/>SDK 1.0+ |
 
 ## Installation