Incorporate an OTel-wide maturity matrix (#290)

* Incorporate an OTel-wide maturity matrix

Per the header comment for the file under review here:

  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.

* Update maturity-matrix.yaml

add golang status, add additional states.

* Update per review comments.

* Respond to review comments and GC feedback

* Add a notApplicable option for API maturity

Co-authored-by: Liz Fong-Jones <elizabeth@ctyalcove.org>
Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>

maturity-matrix.yaml

@@ -0,0 +1,175 @@
+# 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: that is, the component is used in support of well-known product
+  # functionality at publicly-held companies. Nevertheless, either due to
+  # the uncertainty introduced by active development or a small number of
+  # production environments, 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
+
+  # "notApplicable" APIs do not and will never exist for the component/language
+  # because they are, well, not applicable. For instance, a
+  # zero-code-modification auto-instrumentation agent would be notApplicable
+  # for C99.
+  - notApplicable
+
+  # "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.
+  #
+  # Also, for an API to be considered "beta", it must be supported by at least
+  # two complete implementations, and at least one of those must be for a
+  # well-known OSS project (e.g., Jaeger or Prometheus).
+  - 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
+
+# The maturity of the "standaloneComponents" is independent of any particular
+# end-user programming language.
+standaloneComponents:
+  collector:
+    api: alpha
+    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:
+#   pascal:
+#     repoUrl: "https://github.com/open-telemetry/opentelemetry-pascal"
+#     maturityUrl: "https://raw.githubusercontent.com/open-telemetry/opentelemetry-pascal/master/maturity.yaml"
+languages:
+  java:
+    repoUrl: "https://github.com/open-telemetry/opentelemetry-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
+
+  # TODO once we've converged on the schema for all of this
+  js: ""
+  dotnet: ""
+  ruby: ""
+  erlang: ""
+  python: ""
+  golang:
+    repoUrl: "https://github.com/open-telemetry/opentelemetry-go"
+    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
+  php: ""
+  cpp: ""
+  rust: ""