diff --git a/.github/component_owners.yml b/.github/component_owners.yml index 2fa7d000315..a178953c10a 100644 --- a/.github/component_owners.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 692d82b780d..3c2b7513bc2 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 6168d94a799..06cf359193d 100644 --- a/README.md +++ b/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 diff --git a/detectors/node/opentelemetry-resource-detector-aws/README.md b/detectors/node/opentelemetry-resource-detector-aws/README.md index e397892e9db..690c25700db 100644 --- a/detectors/node/opentelemetry-resource-detector-aws/README.md +++ b/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+
SDK 1.0+ | ## Installation diff --git a/packages/opentelemetry-id-generator-aws-xray/README.md b/packages/opentelemetry-id-generator-aws-xray/README.md index f314d2f2172..707cddadbb6 100644 --- a/packages/opentelemetry-id-generator-aws-xray/README.md +++ b/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+
SDK 1.0+ | ## Installation -` +```bash npm install --save @opentelemetry/id-generator-aws-xray -` +``` ## Usage diff --git a/propagators/opentelemetry-propagator-aws-xray/README.md b/propagators/opentelemetry-propagator-aws-xray/README.md index a1c3ad536e6..9f2cb4e307c 100644 --- a/propagators/opentelemetry-propagator-aws-xray/README.md +++ b/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+
SDK 1.0+ | ## Installation