Document public ifaces to remain stable

Resolve open-telemetry#3673

sdk/metric/aggregation/aggregation.go

@@ -32,9 +32,13 @@ type Aggregation interface {
 
 	// Copy returns a deep copy of the Aggregation.
 	Copy() Aggregation
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// Err returns an error for any misconfigured Aggregation.
 	Err() error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // Drop is an aggregation that drops all recorded data.

sdk/metric/exporter.go

@@ -34,12 +34,16 @@ type Exporter interface {
 	// This method needs to be concurrent safe with itself and all the other
 	// Exporter methods.
 	Temporality(InstrumentKind) metricdata.Temporality
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// Aggregation returns the Aggregation to use for an instrument kind.
 	//
 	// This method needs to be concurrent safe with itself and all the other
 	// Exporter methods.
 	Aggregation(InstrumentKind) aggregation.Aggregation
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// Export serializes and transmits metric data to a receiver.
 	//
@@ -56,6 +60,8 @@ type Exporter interface {
 	// exporter needs to hold this data after it returns, it needs to make a
 	// copy.
 	Export(context.Context, *metricdata.ResourceMetrics) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// ForceFlush flushes any metric data held by an exporter.
 	//
@@ -64,6 +70,8 @@ type Exporter interface {
 	//
 	// This method needs to be concurrent safe.
 	ForceFlush(context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// Shutdown flushes all metric data held by an exporter and releases any
 	// held computational resources.
@@ -76,4 +84,6 @@ type Exporter interface {
 	//
 	// This method needs to be concurrent safe.
 	Shutdown(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/metric/reader.go

@@ -56,13 +56,17 @@ type Reader interface {
 	// The producer argument allows the Reader to signal the sdk to collect
 	// and send aggregated metric measurements.
 	register(sdkProducer)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// RegisterProducer registers a an external Producer with this Reader.
 	// The Producer is used as a source of aggregated metric data which is
 	// incorporated into metrics collected from the SDK.
 	//
 	// This method needs to be concurrent safe.
 	RegisterProducer(Producer)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// temporality reports the Temporality for the instrument kind provided.
 	//
@@ -83,6 +87,8 @@ type Reader interface {
 	// This method needs to be concurrent safe, and the cancelation of the
 	// passed context is expected to be honored.
 	Collect(ctx context.Context, rm *metricdata.ResourceMetrics) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// ForceFlush flushes all metric measurements held in an export pipeline.
 	//
@@ -93,6 +99,8 @@ type Reader interface {
 	//
 	// This method needs to be concurrent safe.
 	ForceFlush(context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 
 	// Shutdown flushes all metric measurements held in an export pipeline and releases any
 	// held computational resources.
@@ -107,6 +115,8 @@ type Reader interface {
 	//
 	// This method needs to be concurrent safe.
 	Shutdown(context.Context) error
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // sdkProducer produces metrics for a Reader.
@@ -123,6 +133,8 @@ type Producer interface {
 	//
 	// This method should be safe to call concurrently.
 	Produce(context.Context) ([]metricdata.ScopeMetrics, error)
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
 }
 
 // produceHolder is used as an atomic.Value to wrap the non-concrete producer