diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eec0975eb5a..541e5610639 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -380,7 +380,7 @@ func NewDog(name string, o ...DogOption) Dog {…} func NewBird(name string, o ...BirdOption) Bird {…} ``` -### Interface Type +### Interfaces To allow other developers to better comprehend the code, it is important to ensure it is sufficiently documented. One simple measure that contributes @@ -388,6 +388,30 @@ to this aim is self-documenting by naming method parameters. Therefore, where appropriate, methods of every exported interface type should have their parameters appropriately named. +#### Interface Stability + +From the perspective of users that will only ever call exported interface +type's methods but never implement an interface, this project will always +provide stable interfaces. + +However for users that build implementations of exported interfaces it is +important to understand the type of interface they are implementing as not all +interfaces in this project are stable from an implementation perspective. The +OpenTelemetry API is allowed to accrete functionality. This means that the +interfaces representing this part of the OpenTelemetry API will have methods +added to them. + +Implementation is only ever expected by SDK developers. These developers are +assumed to have an added responsibility of handling these breaking changes to +the interface and resolving them in the evolution of their SDKs. + +All interfaces that include the following warning in their doumentation are +allowed to be extended with additional methods being add to them. + +> Warning: methods may be added to this interface in minor releases. + +Otherwise, stable interfaces MUST NOT be modified. + ## Approvers and Maintainers Approvers: