Interface stability documentation

VERSIONING.md

@@ -12,7 +12,17 @@ is designed so the following goals can be achieved.
   * [Semantic import
     versioning](https://github.com/golang/go/wiki/Modules#semantic-import-versioning)
     will be used.
-    * Versions will comply with [semver 2.0](https://semver.org/spec/v2.0.0.html).
+    * Versions will comply with [semver 2.0](https://semver.org/spec/v2.0.0.html) with the following exceptions.
+      * New methods may be added to exported API interfaces. These
+        interfaces are exported for the sole purpose that SDKs will
+        implement them. Any and all SDKs assume the responsibility that
+        they will resolve this backwards-incompatible change when they
+        upgrade the SDK to support a newer API. All exported interfaces that
+        fall within this exception will include the following paragraph in
+        their public documentation.
+
+        > Warning: methods may be added to this interface in minor releases.
+
     * If a module is version `v2` or higher, the major version of the module
       must be included as a `/vN` at the end of the module paths used in
       `go.mod` files (e.g., `module go.opentelemetry.io/otel/v2`, `require

error_handler.go

@@ -16,7 +16,12 @@ package otel // import "go.opentelemetry.io/otel"
 
 // ErrorHandler handles irremediable events.
 type ErrorHandler interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Handle handles any error deemed irremediable by an OpenTelemetry
 	// component.
 	Handle(error)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }

exporters/otlp/otlptrace/clients.go

@@ -24,10 +24,16 @@ import (
 // transformation of data into wire format, and the transmission of that
 // data to the collector.
 type Client interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Start should establish connection(s) to endpoint(s). It is
 	// called just once by the exporter, so the implementation
 	// does not need to worry about idempotence and locking.
 	Start(ctx context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Stop should close the connections. The function is called
 	// only once by the exporter, so the implementation does not
 	// need to worry about idempotence, but it may be called
@@ -36,8 +42,13 @@ type Client interface {
 	// synchronization point - after the function returns, the
 	// process of closing connections is assumed to be finished.
 	Stop(ctx context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// UploadTraces should transform the passed traces to the wire
 	// format and send it to the collector. May be called
 	// concurrently.
 	UploadTraces(ctx context.Context, protoSpans []*tracepb.ResourceSpans) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }

propagation/propagation.go

@@ -21,12 +21,23 @@ import (
 
 // TextMapCarrier is the storage medium used by a TextMapPropagator.
 type TextMapCarrier interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Get returns the value associated with the passed key.
 	Get(key string) string
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Set stores the key-value pair.
 	Set(key string, value string)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Keys lists the keys stored in this carrier.
 	Keys() []string
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // HeaderCarrier adapts http.Header to satisfy the TextMapCarrier interface.
@@ -54,12 +65,23 @@ func (hc HeaderCarrier) Keys() []string {
 // TextMapPropagator propagates cross-cutting concerns as key-value text
 // pairs within a carrier that travels in-band across process boundaries.
 type TextMapPropagator interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Inject set cross-cutting concerns from the Context into the carrier.
 	Inject(ctx context.Context, carrier TextMapCarrier)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Extract reads cross-cutting concerns from the carrier into a Context.
 	Extract(ctx context.Context, carrier TextMapCarrier) context.Context
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Fields returns the keys who's values are set with Inject.
 	Fields() []string
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 type compositeTextMapPropagator []TextMapPropagator

sdk/resource/auto.go

@@ -29,12 +29,17 @@ var (
 
 // Detector detects OpenTelemetry resource information
 type Detector interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Detect returns an initialized Resource based on gathered information.
 	// If the source information to construct a Resource contains invalid
 	// values, a Resource is returned with the valid parts of the source
 	// information used for initialization along with an appropriately
 	// wrapped ErrPartialResource error.
 	Detect(ctx context.Context) (*Resource, error)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // Detect calls all input detectors sequentially and merges each result with the previous one.

sdk/trace/id_generator.go

@@ -26,8 +26,18 @@ import (
 
 // IDGenerator allows custom generators for TraceID and SpanID.
 type IDGenerator interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
+	// NewIDs returns a new trace and span ID.
 	NewIDs(ctx context.Context) (trace.TraceID, trace.SpanID)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
+	// NewSpanID returns a ID for a new span in the trace with traceID.
 	NewSpanID(ctx context.Context, traceID trace.TraceID) trace.SpanID
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 type randomIDGenerator struct {

sdk/trace/sampling.go

@@ -25,8 +25,19 @@ import (
 
 // Sampler decides whether a trace should be sampled and exported.
 type Sampler interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
+	// ShouldSample returns a SamplingResult based on a decision made from the
+	// passed parameters.
 	ShouldSample(parameters SamplingParameters) SamplingResult
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
+	// Description returns information describing the Sampler.
 	Description() string
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // SamplingParameters contains the values passed to a Sampler.

sdk/trace/span.go

@@ -35,47 +35,97 @@ import (
 // trace.Span. It is used in places where reading information from a span is
 // necessary but changing the span isn't necessary or allowed.
 type ReadOnlySpan interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Name returns the name of the span.
 	Name() string
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// SpanContext returns the unique SpanContext that identifies the span.
 	SpanContext() trace.SpanContext
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Parent returns the unique SpanContext that identifies the parent of the
 	// span if one exists. If the span has no parent the returned SpanContext
 	// will be invalid.
 	Parent() trace.SpanContext
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// SpanKind returns the role the span plays in a Trace.
 	SpanKind() trace.SpanKind
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// StartTime returns the time the span started recording.
 	StartTime() time.Time
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// EndTime returns the time the span stopped recording. It will be zero if
 	// the span has not ended.
 	EndTime() time.Time
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Attributes returns the defining attributes of the span.
 	Attributes() []attribute.KeyValue
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Links returns all the links the span has to other spans.
 	Links() []trace.Link
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Events returns all the events that occurred within in the spans
 	// lifetime.
 	Events() []Event
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Status returns the spans status.
 	Status() Status
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// InstrumentationLibrary returns information about the instrumentation
 	// library that created the span.
 	InstrumentationLibrary() instrumentation.Library
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Resource returns information about the entity that produced the span.
 	Resource() *resource.Resource
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// DroppedAttributes returns the number of attributes dropped by the span
 	// due to limits being reached.
 	DroppedAttributes() int
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// DroppedLinks returns the number of links dropped by the span due to
 	// limits being reached.
 	DroppedLinks() int
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// DroppedEvents returns the number of events dropped by the span due to
 	// limits being reached.
 	DroppedEvents() int
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// ChildSpanCount returns the count of spans that consider the span a
 	// direct parent.
 	ChildSpanCount() int
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// A private method to prevent users implementing the
 	// interface and so future additions to it will not
@@ -89,8 +139,16 @@ type ReadOnlySpan interface {
 // "write-only" span) and ReadOnlySpan. New methods for writing or reading span
 // information should be added under trace.Span or ReadOnlySpan, respectively.
 type ReadWriteSpan interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	trace.Span
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	ReadOnlySpan
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // span is an implementation of the OpenTelemetry Span API representing the

sdk/trace/span_exporter.go

@@ -19,6 +19,9 @@ import "context"
 // SpanExporter handles the delivery of spans to external receivers. This is
 // the final component in the trace export pipeline.
 type SpanExporter interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// ExportSpans exports a batch of spans.
 	//
 	// This function is called synchronously, so there is no concurrency
@@ -31,9 +34,14 @@ type SpanExporter interface {
 	// returned by this function are considered unrecoverable and will be
 	// reported to a configured error Handler.
 	ExportSpans(ctx context.Context, spans []ReadOnlySpan) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Shutdown notifies the exporter of a pending halt to operations. The
 	// exporter is expected to preform any cleanup or synchronization it
 	// requires while honoring all timeouts and cancellations contained in
 	// the passed context.
 	Shutdown(ctx context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }

sdk/trace/span_processor.go

@@ -24,13 +24,20 @@ import (
 // and end of a Span's lifecycle, and are called in the order they are
 // registered.
 type SpanProcessor interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// OnStart is called when a span is started. It is called synchronously
 	// and should not block.
 	OnStart(parent context.Context, s ReadWriteSpan)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// OnEnd is called when span is finished. It is called synchronously and
 	// hence not block.
 	OnEnd(s ReadOnlySpan)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// Shutdown is called when the SDK shuts down. Any cleanup or release of
 	// resources held by the processor should be done in this call.
@@ -41,12 +48,16 @@ type SpanProcessor interface {
 	// All timeouts and cancellations contained in ctx must be honored, this
 	// should not block indefinitely.
 	Shutdown(ctx context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// ForceFlush exports all ended spans to the configured Exporter that have not yet
 	// been exported.  It should only be called when absolutely necessary, such as when
 	// using a FaaS provider that may suspend the process after an invocation, but before
 	// the Processor can export the completed spans.
 	ForceFlush(ctx context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 type spanProcessorState struct {

trace/trace.go

@@ -337,6 +337,8 @@ func (sc SpanContext) MarshalJSON() ([]byte, error) {
 // and timed operation of a workflow that is traced. A Tracer is used to
 // create a Span and it is then up to the operation the Span represents to
 // properly end the Span when the operation itself ends.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Span interface {
 	// End completes the Span. The Span is considered complete and ready to be
 	// delivered through the rest of the telemetry pipeline after this method
@@ -478,6 +480,8 @@ func (sk SpanKind) String() string {
 }
 
 // Tracer is the creator of Spans.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Tracer interface {
 	// Start creates a span and a context.Context containing the newly-created span.
 	//
@@ -496,6 +500,8 @@ type Tracer interface {
 }
 
 // TracerProvider provides access to instrumentation Tracers.
+//
+// Warning: methods may be added to this interface in minor releases.
 type TracerProvider interface {
 	// Tracer creates an implementation of the Tracer interface.
 	// The instrumentationName must be the name of the library providing