Document public metric SDK interfaces to remain stable (#4396)

* Document public ifaces to remain stable

Resolve #3673

* Revert changes to aggregation pkg

* Document reader as an interface that can be extended

* Address feedback

---------

Co-authored-by: Chester Cheung <cheung.zhy.csu@gmail.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>

sdk/metric/exporter.go

@@ -33,12 +33,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
+	// 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.
 	//
@@ -55,6 +59,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.
 	//
@@ -63,6 +69,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.
@@ -75,4 +83,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

@@ -50,6 +50,8 @@ var errNonPositiveDuration = fmt.Errorf("non-positive duration")
 //
 // Pull-based exporters will typically implement Register
 // themselves, since they read on demand.
+//
+// Warning: methods may be added to this interface in minor releases.
 type Reader interface {
 	// register registers a Reader with a MeterProvider.
 	// The producer argument allows the Reader to signal the sdk to collect
@@ -75,6 +77,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.
 
 	// Shutdown flushes all metric measurements held in an export pipeline and releases any
 	// held computational resources.
@@ -89,6 +93,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.
@@ -101,10 +107,15 @@ type sdkProducer interface {
 
 // Producer produces metrics for a Reader from an external source.
 type Producer interface {
+	// DO NOT CHANGE: any modification will not be backwards compatible and
+	// must never be done outside of a new major release.
+
 	// Produce returns aggregated metrics from an external source.
 	//
 	// 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