Rename Experimental to Development according to OTEP 0232 (#4061)

Resolves #4051 [OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md) brought new stability definitions. The impact on this repository is that we need to rename "Experimental" to "Development". All other existing statuses remain unchanged. Note: OTEP 0232 also introduces other levels, such as Alpha, Beta, etc. We will need to decide separately if we want to start using these levels in this repository.
open-telemetry · Jun 4, 2024 · c861b8e · c861b8e
1 parent d0bfe08
commit c861b8e
Show file tree

Hide file tree

Showing 29 changed files with 101 additions and 88 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -16,15 +16,15 @@
 *   @open-telemetry/technical-committee @open-telemetry/specs-approvers
 
 # Trace owners (global + trace)
-experimental/trace/     @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers
+development/trace/     @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers
 specification/trace/    @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers
 
 # Metrics owners (global + metrics)
-experimental/metrics/   @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers
+development/metrics/   @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers
 specification/metrics/  @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers
 
 # Logs owners (global + logs)
-experimental/logs/      @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers
+development/logs/      @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers
 specification/logs/     @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers
 
 # Semantic Conventions owners (global)

diff --git a/development/README.md b/development/README.md
@@ -0,0 +1,20 @@
+# Features in Development
+
+This folder is used for features in
+[Development](../specification/document-status.md). `Development` status is for components
+that are on track to become part of the specification, but that require a faster cadence
+of merges and collaboration.
+
+Features in Development must be:
+
+- Implementable as a plugin to OpenTelemetry components (API, SDK, collector, etc.).
+- Be in active development or testing.
+- Approved as a general direction via OTEP process.
+
+To avoid any confusion, all files in this directory must have a note about its Development status.
+
+Development status precedes the alpha version (see
+[OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#explanation)).
+All changes in the `development` folder go through the regular review process. Changes are allowed to be merged faster as completeness of a solution is not a requirement. Approval means that proposed changes are OK for experimentation.
+
+When the feature or parts of it are developed far enough to declare them as an alpha version of a main project and move out of the Development status, it must go through a **new** OTEP PR and it must be expected that design and APIs will be changed. In fact, the same people who approved the experiment may likely be the most critical reviewers. It demonstrates an interest and involvement, not critique.
diff --git a/experimental/metrics/config-service.md → development/metrics/config-service.md b/experimental/metrics/config-service.md → development/metrics/config-service.md
@@ -122,7 +122,7 @@ metrics on a push-based model.
 
 ## Implementation Details
 
-Because this specification is experimental, and may imply substantial changes to
+Because this specification is in Development, and may imply substantial changes to
 the existing system, we provide additional details on the example prototype
 implementations available on the
 [contrib collector](https://github.com/vmingchen/opentelemetry-collector-contrib) and

diff --git a/experimental/trace/zpages.md → development/trace/zpages.md b/experimental/trace/zpages.md → development/trace/zpages.md
diff --git a/experimental/README.md b/experimental/README.md
diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -204,7 +204,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
 ## Events
 
 Features for the [Events API](specification/logs/event-api.md) and the [Events SDK](specification/logs/event-sdk.md).
-Disclaimer: Events are currently an experimental work in progress.
+Disclaimer: Events are currently in Development status - work in progress.
 
 | Feature                                                                    | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
 |----------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------|

diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md
@@ -4,7 +4,7 @@ linkTitle: Mapping to AnyValue
 
 # Mapping Arbitrary Data to OTLP AnyValue
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 <details>
 <summary>Table of Contents</summary>

diff --git a/specification/compatibility/logging_trace_context.md b/specification/compatibility/logging_trace_context.md
@@ -1,6 +1,6 @@
 # Trace Context in non-OTLP Log Formats
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 <details>
 <summary>Table of Contents</summary>

diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md
@@ -574,7 +574,7 @@ startSpan(name: string, options: SpanOptions = {}): Span {
 Using both the OpenTracing Shim and the OpenTelemetry API in the same codebase
 may result in traces using the incorrect parent `Span`, given the different
 implicit/explicit propagation expectations. For this case, the Shim MAY offer
-**experimental** integration with the OpenTelemetry implicit in-process
+**in-Development** integration with the OpenTelemetry implicit in-process
 propagation via an **explicit** setting, warning the user incorrect parent
 values may be consumed:
 

diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md
@@ -7,7 +7,7 @@ aliases:
 
 # Prometheus and OpenMetrics Compatibility
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 <details>
 <summary>Table of Contents</summary>

diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md
@@ -4,7 +4,7 @@ linkTitle: File
 
 # File Configuration
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 <!-- toc -->
 

diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md
@@ -225,7 +225,7 @@ _is no specified default, or configuration via environment variables_.
 
 ## Prometheus Exporter
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 | Name                          | Description                     | Default                      |
 | ----------------------------- | --------------------------------| ---------------------------- |
@@ -274,7 +274,7 @@ NOT be supported by new implementations.
 
 ### Exemplar
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 | Name            | Description | Default | Notes |
 |-----------------|---------|-------------|---------|
@@ -298,7 +298,7 @@ that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-
 
 ## File Configuration
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 Environment variables involved in [file configuration](file-configuration.md).
 

diff --git a/specification/document-status.md b/specification/document-status.md
@@ -11,11 +11,15 @@ The support guarantees and allowed changes are governed by the lifecycle of the
 
 |Status              |Explanation|
 |--------------------|-----------|
-|No explicit "Status"|Equivalent to Experimental.|
-|Experimental        |Breaking changes are allowed.|
+|No explicit "Status"|Equivalent to Development.|
+|Development        |Breaking changes are allowed.|
 |Stable              |Breaking changes are no longer allowed. See [stability guarantees](versioning-and-stability.md#stable) for details.|
 |Deprecated          |Changes are no longer allowed, except for editorial changes.|
 
+The specification follows
+[OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#explanation)
+maturity level definitions.
+
 ## Feature freeze
 
 In addition to the statuses above, documents may be marked as `Feature-freeze`. These documents are not currently accepting new feature requests, to allow the Technical Committee time to focus on other areas of the specification. Editorial changes are still accepted. Changes that address production issues with existing features are still accepted.

diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md
@@ -1,6 +1,6 @@
 # Events API
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 <details>
 <summary>Table of Contents</summary>

diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md
@@ -1,6 +1,6 @@
 # Events SDK
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 <details>
 <summary>Table of Contents</summary>

diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md
@@ -71,15 +71,15 @@ working `Logger` MUST be returned as a fallback rather than returning null or
 throwing an exception, its `name` SHOULD keep the original invalid value, and a
 message reporting that the specified value is invalid SHOULD be logged.
 
-**Status**: [Experimental](../document-status.md) - The `LoggerProvider` MUST
+**Status**: [Development](../document-status.md) - The `LoggerProvider` MUST
 compute the relevant [LoggerConfig](#loggerconfig) using the
 configured [LoggerConfigurator](#loggerconfigurator), and create
 a `Logger` whose behavior conforms to that `LoggerConfig`.
 
 ### Configuration
 
 Configuration (
-i.e. [LogRecordProcessors](#logrecordprocessor) and (**experimental**) [LoggerConfigurator](#loggerconfigurator))
+i.e. [LogRecordProcessors](#logrecordprocessor) and (**Development**) [LoggerConfigurator](#loggerconfigurator))
 MUST be owned by the `LoggerProvider`. The configuration MAY be applied at the
 time of `LoggerProvider` creation if appropriate.
 
@@ -93,7 +93,7 @@ configuration only via this reference.
 
 #### LoggerConfigurator
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 A `LoggerConfigurator` is a function which computes
 the [LoggerConfig](#loggerconfig) for a [Logger](#logger).
@@ -163,15 +163,15 @@ registered [LogRecordProcessors](#logrecordprocessor).
 
 ## Logger
 
-**Status**: [Experimental](../document-status.md) - `Logger` MUST behave
+**Status**: [Development](../document-status.md) - `Logger` MUST behave
 according to the [LoggerConfig](#loggerconfig) computed
 during [logger creation](#logger-creation). If the `LoggerProvider` supports
 updating the [LoggerConfigurator](#loggerconfigurator), then upon update
 the `Logger` MUST be updated to behave according to the new `LoggerConfig`.
 
 ### LoggerConfig
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 A `LoggerConfig` defines various configurable aspects of a `Logger`'s behavior.
 It consists of the following parameters:

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -190,7 +190,7 @@ will have the following parameters:
   one of the other kinds, whether it is synchronous or asynchronous
 * An optional `unit` of measure
 * An optional `description`
-* Optional `advisory` parameters (**experimental**)
+* Optional `advisory` parameters (**development**)
 
 Instruments are associated with the Meter during creation. Instruments
 are identified by the `name`, `kind`, `unit`, and `description`.
@@ -274,7 +274,7 @@ boundaries to use if aggregating to
 
 ##### Instrument advisory parameter: `Attributes`
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 Applies to all instrument types.
 

diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md
@@ -1087,7 +1087,7 @@ of cardinality outside of the process.
 
 ## Resets and Gaps
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 When the `StartTimeUnixNano` field is present, it allows the consumer
 to observe when there are gaps and overlapping writers in a stream.
@@ -1161,7 +1161,7 @@ of reaggregation for cumulative series.
 
 ## Overlap
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 Overlap occurs when more than one metric data point is defined for a
 metric stream within a time window.  Overlap is usually caused through
@@ -1200,7 +1200,7 @@ gaps to zero width in these cases, without any overlap.
 
 ## Stream Manipulations
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 Pending introduction.
 

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -132,7 +132,7 @@ When a Schema URL is passed as an argument when creating a `Meter` the emitted
 telemetry for that `Meter` MUST be associated with the Schema URL, provided
 that the emitted data format is capable of representing such association.
 
-**Status**: [Experimental](../document-status.md) - The `MeterProvider` MUST
+**Status**: [Development](../document-status.md) - The `MeterProvider` MUST
 compute the relevant [MeterConfig](#meterconfig) using the
 configured [MeterConfigurator](#meterconfigurator), and create
 a `Meter` whose behavior conforms to that `MeterConfig`.
@@ -141,7 +141,7 @@ a `Meter` whose behavior conforms to that `MeterConfig`.
 
 Configuration (
 i.e. [MetricExporters](#metricexporter), [MetricReaders](#metricreader), [Views](#view),
-and (**experimental**) [MeterConfigurator](#meterconfigurator)) MUST be
+and (**Development**) [MeterConfigurator](#meterconfigurator)) MUST be
 owned by the `MeterProvider`. The configuration MAY be applied at the time
 of `MeterProvider` creation if appropriate.
 
@@ -155,7 +155,7 @@ configuration only via this reference.
 
 #### MeterConfigurator
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 A `MeterConfigurator` is a function which computes
 the [MeterConfig](#meterconfig) for a [Meter](#meter).
@@ -396,7 +396,7 @@ The SDK MUST accept the following stream configuration parameters:
   If the user does not provide an `exemplar_reservoir` value, the
   `MeterProvider` MUST apply a [default exemplar
   reservoir](#exemplar-defaults).
-* **Status**: [Experimental](../document-status.md) -
+* **Status**: [Development](../document-status.md) -
   `aggregation_cardinality_limit`: A positive integer value defining the
   maximum number of data points allowed to be emitted in a collection cycle by
   a single instrument. See [cardinality limits](#cardinality-limits), below.
@@ -771,7 +771,7 @@ of metrics across successive collections.
 
 ### Cardinality limits
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 SDKs SHOULD support being configured with a cardinality limit. The number of
 unique combinations of attributes is called cardinality. For a given metric, the
@@ -837,15 +837,15 @@ temporality.
 Distinct meters MUST be treated as separate namespaces for the purposes of detecting
 [duplicate instrument registrations](#duplicate-instrument-registration).
 
-**Status**: [Experimental](../document-status.md) - `Meter` MUST behave
+**Status**: [Development](../document-status.md) - `Meter` MUST behave
 according to the [MeterConfig](#meterconfig) computed
 during [Meter creation](#meter-creation). If the `MeterProvider` supports
 updating the [MeterConfigurator](#meterconfigurator), then upon update
 the `Meter` MUST be updated to behave according to the new `MeterConfig`.
 
 ### MeterConfig
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 A `MeterConfig` defines various configurable aspects of a `Meter`'s behavior.
 It consists of the following parameters:
@@ -941,7 +941,7 @@ Meter MUST treat it the same as an empty description string.
 
 ### Instrument advisory parameters
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 When a Meter creates an instrument, it SHOULD validate the instrument advisory
 parameters. If an advisory parameter is not valid, the Meter SHOULD emit an error
@@ -1227,11 +1227,11 @@ SHOULD provide at least the following:
 * The `exporter` to use, which is a `MetricExporter` instance.
 * The default output `aggregation` (optional), a function of instrument kind.  If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
 * The default output `temporality` (optional), a function of instrument kind.  If not configured, the Cumulative temporality SHOULD be used.
-* **Status**: [Experimental](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind.  If not configured, a default value of 2000 SHOULD be used.
-* **Status**: [Experimental](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`.
+* **Status**: [Development](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind.  If not configured, a default value of 2000 SHOULD be used.
+* **Status**: [Development](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`.
 * Zero of more [MetricProducer](#metricproducer)s (optional) to collect metrics from in addition to metrics from the SDK.
 
-**Status**: [Experimental](../document-status.md) - A `MetricReader` SHOULD provide the [MetricFilter](#metricfilter) to the SDK or registered [MetricProducer](#metricproducer)(s)
+**Status**: [Development](../document-status.md) - A `MetricReader` SHOULD provide the [MetricFilter](#metricfilter) to the SDK or registered [MetricProducer](#metricproducer)(s)
 when calling the `Produce` operation.
 
 The [MetricReader.Collect](#collect) method allows general-purpose
@@ -1680,11 +1680,11 @@ If a batch of [Metric Points](./data-model.md#metric-points) can include
 
 **Parameters:**
 
-**Status**: [Experimental](../document-status.md) `metricFilter`: An optional [MetricFilter](#metricfilter).
+**Status**: [Development](../document-status.md) `metricFilter`: An optional [MetricFilter](#metricfilter).
 
 ## MetricFilter
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 `MetricFilter` defines the interface which enables the [MetricReader](#metricreader)'s
 registered [MetricProducers](#metricproducer) or the SDK's [MetricProducer](#metricproducer) to filter aggregated data points

diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md
@@ -4,7 +4,7 @@ linkTitle: Prometheus
 
 # Metrics Exporter - Prometheus
 
-**Status**: [Experimental](../../document-status.md)
+**Status**: [Development](../../document-status.md)
 
 A Prometheus Exporter MUST be a [Pull Metric Exporter](../sdk.md#pull-metric-exporter)
 which responds to HTTP requests with Prometheus metrics in the appropriate format.

diff --git a/specification/protocol/file-exporter.md b/specification/protocol/file-exporter.md
@@ -4,7 +4,7 @@ linkTitle: File Exporter
 
 # OpenTelemetry Protocol File Exporter
 
-**Status**: [Experimental](../../specification/document-status.md)
+**Status**: [Development](../../specification/document-status.md)
 
 This document provides a placeholder for specifying an OTLP exporter capable of
 exporting to either a file or stdout.

diff --git a/specification/schemas/file_format_v1.0.0.md b/specification/schemas/file_format_v1.0.0.md
@@ -4,7 +4,7 @@ linkTitle: 1.0.0
 
 # Schema File Format 1.0.0
 
-**Status**: [Experimental](../document-status.md)
+**Status**: [Development](../document-status.md)
 
 A Schema File is a YAML file that describes the schema of a particular version.
 It defines the transformations that can be used to convert the telemetry data