Incorporate an OTel-wide maturity matrix

maturity-matrix.yaml

@@ -0,0 +1,161 @@
+# OpenTelemetry is a complex project with many moving parts. Thankfully, we
+# strive to keep those parts loosely coupled where we can (this has been a goal
+# since the very announcement of OpenTelemetry, per this blog post:
+# https://medium.com/opentracing/merging-opentracing-and-opencensus-f0fe9c7ca6f0)
+#
+# This file describes the structure of the project and its sub-components,
+# definitions of API and stability maturity levels, and finally records the
+# current maturity of each component. We maintain this file as YAML in order to
+# make it easier to automate scripts (e.g., for the website) that present the
+# data to OpenTelemetry end-users.
+
+
+###############################################################################
+# MATURITY LEVELS
+#
+# OpenTelemetry components advertise their own maturity along two axes:
+# - PRODUCTION MATURITY: How reliable is this component from a
+#   production-readiness standpoint?
+# - API MATURITY: How stable is the component's API from a backwards- and
+#   forwards-compatibility standpoint)?
+#
+# In some cases, for instance, OpenTelemetry components may be immature from an
+# API maturity standpoint, yet be nearly 100% safe from a production standpoint
+# – and vice versa. Similarly, end-users may have more tolerance for lost
+# development time or software stability depending on their situation, so we
+# strive to separate self-reported maturity along these two axes.
+#
+# Needless to say, representations here are best-effort, and there is no
+# substitute for a mature release process. I.e., don't blindly deploy "mature"
+# OpenTelemetry components (or any software, for that matter!).
+productionMaturityLevels:
+  # "unknown" maturity is just what it purports to be. It's reasonable to
+  # assume "unstable", but we separate "unknown" and "unstable" to distinguish
+  # between a lack of evidence about production maturity and actual evidence of
+  # immaturity.
+  - unknown
+  # "unstable" components are not recommended for production workloads. They
+  # may crash the process, introduce performance artifacts, or have known
+  # security issues.
+  - unstable
+  # "beta" components have been used successfully in production workloads at
+  # scale, but either due to the uncertainty introduced by active development
+  # or a small number of production deployments, they should still be used
+  # cautiously in new deployments. They do not have known security issues.
+  - beta
+  # "stable" components are, to the best of the author's knowledge, safe for
+  # typical production use cases.
+  - stable
+
+# All OpenTelemetry APIs follow semver conventions (i.e., after v1.x,
+# backwards-incompatible changes should bump the major version number).
+apiMaturityLevels:
+  # "unimplemented" APIs do not exist yet for the component/language.
+  - unimplemented
+  # "alpha" maturity APIs can change in incompatible ways at any time.
+  - alpha
+  # "beta" maturity APIs should not introduce backwards-incompatible changes
+  # more than once every three months; and when those changes are introduced, the
+  # authors will make a best effort to provide compatibility bridges.
+  - beta
+  # "stable" maturity APIs should not introduce backwards-incompatible changes
+  # more than once every twelve months, and will make every effort to provide
+  # compatibility bridges if at all possible.
+  - stable
+
+
+###############################################################################
+# OPENTELEMETRY COMPONENTS
+#
+# Some OpenTelemetry components run within end-user applications and thus have
+# a footprint across many languages. Naturally, the production and API maturity
+# of these components varies from language to language. Other components run as
+# infrastructure in their own containers or VMs and thus have a single maturity
+# level regardless of the end-user's programming language.
+#
+# The maturity – or even the existence – of the "perLanguageComponents" varies
+# from language to language. These are components that integrate into the
+# actual end-user application runtime in production. See "languages" for the
+# actual maturity levels.
+perLanguageComponents:
+  - traceAPI
+  - metricsAPI
+  - contextAPI
+  - traceSDK
+  - metricsSDK
+  - contextSDK
+  - automaticInstrumentation
+
+# The maturity of the "standaloneComponents" is independent of any particular
+# end-user programming language.
+standaloneComponents:
+  collector:
+    api: beta
+    production: beta
+  operator:
+    api: alpha
+    production: beta
+
+# For each language, we either specify the perLanguageComponents maturity
+# inline, or we specify a single "url" that points to another YAML file with a
+# top-level perLanguageComponents key (presumably in the OpenTelemetry language
+# repository). E.g., something like this:
+#
+# languages:
+#   logo:
+#     url: "https://raw.githubusercontent.com/open-telemetry/opentelemetry-logo/master/maturity.yaml"
+languages:
+  java:
+    traceAPI:
+      api: alpha
+      production: beta
+    metricsAPI:
+      api: alpha
+      production: beta
+    contextAPI:
+      api: alpha
+      production: beta
+    traceSDK:
+      api: alpha
+      production: unstable
+    metricsSDK:
+      api: alpha
+      production: unstable
+    contextSDK:
+      api: alpha
+      production: unstable
+    automaticInstrumentation:
+      api: beta
+      production: unstable
+
+  # TODO once we've converged on the schema for all of this
+  js: ""
+  dotnet: ""
+  ruby: ""
+  erlang: ""
+  python: ""
+  golang:
+    traceAPI:
+      api: beta
+      production: beta
+    metricsAPI:
+      api: alpha
+      production: beta
+    contextAPI:
+      api: unimplemented
+      production: unknown
+    traceSDK:
+      api: beta
+      production: beta
+    metricsSDK:
+      api: alpha
+      production: unstable
+    contextSDK:
+      api: unimplemented
+      production: unknown
+    automaticInstrumentation:
+      api: unimplemented
+      production: unknown
+  php: ""
+  cpp: ""
+  rust: ""