Update README and documentation to better communicate pre-GA state (#1281)

* Update README

Move project status to top of project documentation and add explicit
warnings that this project may introduce breaking changes.

* Add disclaimer to public packages docs

* Use explicit warning in README

README.md

@@ -7,6 +7,22 @@
 
 The Go [OpenTelemetry](https://opentelemetry.io/) implementation.
 
+## Project Status
+
+**Warning**: this project is currently in a pre-GA phase. Backwards
+incompatible changes may be introduced in subsequent minor version releases as
+we work to track the evolving OpenTelemetry specification and user feedback.
+
+Our progress towards a GA release candidate is tracked in [this project
+board](https://github.com/orgs/open-telemetry/projects/5). This release
+candidate will follow semantic versioning and will be released with a major
+version greater than zero.
+
+Progress and status specific to this repository is tracked in our local
+[project boards](https://github.com/open-telemetry/opentelemetry-go/projects)
+and
+[milestones](https://github.com/open-telemetry/opentelemetry-go/milestones).
+
 ## Getting Started
 
 OpenTelemetry's goal is to provide a single set of APIs to capture distributed
@@ -45,18 +61,6 @@ and
 [metric](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/export/metric?tab=importedby)
 support.
 
-## Project Status
-
-This project is currently in a pre-GA phase. Our progress towards a GA release
-candidate is tracked in [this project
-board](https://github.com/orgs/open-telemetry/projects/5).
-
-Progress and status specific to this repository is tracked in our local
-[project boards](https://github.com/open-telemetry/opentelemetry-go/projects)
-and [milestones](https://github.com/open-telemetry/opentelemetry-go/milestones)
-can be found at the respective links. We try to keep these accurate and should
-be the best place to go for answers on project status.
-
 ## Contributing
 
 See the [contributing documentation](CONTRIBUTING.md).

codes/codes.go

@@ -14,6 +14,10 @@
 
 // Package codes defines the canonical error codes used by OpenTelemetry.
 //
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
+//
 // It conforms to [the OpenTelemetry
 // specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#statuscanonicalcode).
 package codes // import "go.opentelemetry.io/otel/codes"

doc.go

@@ -15,6 +15,10 @@
 /*
 Package otel provides an implementation of the OpenTelemetry API.
 
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
 The provided API is used to instrument code and measure data about that code's
 performance and operation. The measured data, by default, is not processed or
 transmitted anywhere. An implementation of the OpenTelemetry SDK, like the

exporters/otlp/doc.go

@@ -13,4 +13,8 @@
 // limitations under the License.
 
 // Package otlp contains an exporter for the OpenTelemetry protocol buffers.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package otlp // import "go.opentelemetry.io/otel/exporters/otlp"

exporters/stdout/doc.go

@@ -14,4 +14,8 @@
 
 // Package stdout contains an OpenTelemetry exporter for both tracing and
 // metric telemetry to be written to an output destination as JSON.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package stdout // import "go.opentelemetry.io/otel/exporters/stdout"

exporters/trace/jaeger/doc.go

@@ -13,4 +13,8 @@
 // limitations under the License.
 
 // Package jaeger contains an OpenTelemetry tracing exporter for Jaeger.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package jaeger // import "go.opentelemetry.io/otel/exporters/trace/jaeger"

exporters/trace/zipkin/doc.go

@@ -13,4 +13,8 @@
 // limitations under the License.
 
 // Package zipkin contains an OpenTelemetry tracing exporter for Zipkin.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package zipkin // import "go.opentelemetry.io/otel/exporters/trace/zipkin"

global/doc.go

@@ -13,4 +13,8 @@
 // limitations under the License.
 
 // Package global provides global providers, propagators and more.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package global // import "go.opentelemetry.io/otel/global"

label/doc.go

@@ -13,4 +13,8 @@
 // limitations under the License.
 
 // Package label provides key and value labels.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package label // import "go.opentelemetry.io/otel/label"

oteltest/doc.go

@@ -15,6 +15,10 @@
 /*
 Package oteltest provides testing utilities for the otel package.
 
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
 API Validation
 
 The Harness can be used to validate an implementation of the OpenTelemetry API

propagators/doc.go

@@ -15,6 +15,10 @@
 /*
 Package propagators contains OpenTelemetry context propagators.
 
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
 OpenTelemetry propagators are used to extract and inject context data from and
 into messages exchanged by applications. The propagator supported by this
 package is the W3C Trace Context encoding

sdk/instrumentation/library.go

@@ -16,6 +16,10 @@
 Package instrumentation provides an instrumentation library structure to be
 passed to both the OpenTelemetry Tracer and Meter components.
 
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
 For more information see
 [this](https://github.com/open-telemetry/oteps/blob/master/text/0083-component.md).
 */

sdk/metric/doc.go

@@ -13,14 +13,19 @@
 // limitations under the License.
 
 /*
-Package metric implements the OpenTelemetry metric.MeterImpl
+Package metric implements the OpenTelemetry metric API.
-interface.  The Accumulator type supports configurable metrics export
-behavior through a collection of export interfaces that support
-various export strategies, described below.
 
-The metric.MeterImpl API consists of methods for constructing
+This package is currently in a pre-GA phase. Backwards incompatible changes
-synchronous and asynchronous instruments.  There are two constructors
+may be introduced in subsequent minor version releases as we work to track the
-per instrument for the two kinds of number (int64, float64).
+evolving OpenTelemetry specification and user feedback.
+
+The Accumulator type supports configurable metrics export behavior through a
+collection of export interfaces that support various export strategies,
+described below.
+
+The OpenTelemetry metric API consists of methods for constructing synchronous
+and asynchronous instruments.  There are two constructors per instrument for
+the two kinds of number (int64, float64).
 
 Synchronous instruments are managed by a sync.Map containing a *record
 with the current state for each synchronous instrument.  A bound

sdk/metric/processor/reducer/doc.go

@@ -13,11 +13,17 @@
 // limitations under the License.
 
 /*
-Package reducer implements a metrics Processor component that applies
+Package reducer implements a metrics Processor component to reduce labels.
-a `label.Filter` to each processed `export.Accumulation` to remove
+
-labels before passing the result to another Processor.  This Processor
+This package is currently in a pre-GA phase. Backwards incompatible changes
-can be used to reduce inherent dimensionality in the data, as a way to
+may be introduced in subsequent minor version releases as we work to track the
-control the cost of collecting high cardinality metric data.
+evolving OpenTelemetry specification and user feedback.
+
+The metrics Processor component this package implements applies a
+`label.Filter` to each processed `export.Accumulation` to remove labels before
+passing the result to another Processor.  This Processor can be used to reduce
+inherent dimensionality in the data, as a way to control the cost of
+collecting high cardinality metric data.
 
 For example, to compose a push controller with a reducer and a basic
 metric processor:

sdk/opentelemetry.go

@@ -13,6 +13,10 @@
 // limitations under the License.
 
 // Package opentelemetry contains Go support for OpenTelemetry.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package opentelemetry // import "go.opentelemetry.io/otel/sdk"
 
 // Version is the current release version of OpenTelemetry in use.

sdk/resource/doc.go

@@ -14,6 +14,10 @@
 
 // Package resource provides detecting and representing resources.
 //
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
+//
 // The fundamental struct is a Resource which holds identifying information
 // about the entities for which telemetry is exported.
 //

sdk/trace/doc.go

@@ -15,6 +15,10 @@
 /*
 Package trace contains support for OpenTelemetry distributed tracing.
 
+This package is currently in a pre-GA phase. Backwards incompatible changes
+may be introduced in subsequent minor version releases as we work to track the
+evolving OpenTelemetry specification and user feedback.
+
 The following assumes a basic familiarity with OpenTelemetry concepts.
 See https://opentelemetry.io.
 */

semconv/doc.go

@@ -14,6 +14,10 @@
 
 // Package semconv implements OpenTelemetry semantic conventions.
 //
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
+//
 // OpenTelemetry semantic conventions are agreed standardized naming
 // patterns for OpenTelemetry things. This package aims to be the
 // centralized place to interact with these conventions.

unit/doc.go

@@ -13,4 +13,8 @@
 // limitations under the License.
 
 // Package unit provides units.
+//
+// This package is currently in a pre-GA phase. Backwards incompatible changes
+// may be introduced in subsequent minor version releases as we work to track
+// the evolving OpenTelemetry specification and user feedback.
 package unit // import "go.opentelemetry.io/otel/unit"