[chore][VERSIONING.md] Document approach to optional experimental interfaces #11482
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #11482 +/- ##
=======================================
Coverage 91.48% 91.48%
=======================================
Files 433 433
Lines 23617 23617
=======================================
Hits 21607 21607
Misses 1642 1642
Partials 368 368 ☔ View full report in Codecov by Sentry. |
| @@ -62,6 +62,9 @@ Unless otherwise specified in the documentation, the following may change in any | |||
| * **Protocol compatibility**. Changing the default minimum version of a supported protocol (e.g. TLS) or dropping support for protocols when there are security concerns is not considered a breaking change. | |||
| * **Dependency updates**. Updating dependencies is not considered a breaking change except when their types are part of the | |||
| public API or the update may change the behavior of applications in an incompatible way. | |||
| * **Underlying type for interfaces**. If a struct exported as an interface has an experimental | |||
| method, this method may change or be removed in a minor version. The method will be published in an | |||
| optional interface under an experimental module to signal it is experimental. | |||
There was a problem hiding this comment.
Should the method also be documented as experimental?
There was a problem hiding this comment.
If the method is in an experimental module (one released under v0.x), do you think this is needed?
There was a problem hiding this comment.
Ah, sorry, I thought you were allowing struct methods to be defined in stable modules, as long as they were defined in experimental interfaces.
There was a problem hiding this comment.
Sorry, still confused 😅 To make it more clear: let's talk about the case of the otlpreceiver.NewFactory function.
The NewFactory function returns receiver.Factory. The underlying struct that is returned by this function also implements the receiverprofiles.Factory interface. I want to make sure we write down that it is fine to change the extra methods in receiverprofiles.Factory (i.e. CreateProfiles) in a minor version. How can we best write this?
Right now, since receiverprofiles.Factory is in a different module it can remain 0.x while the receiver module goes 1.x, and this rule allows changes in CreateProfiles. Is this okay? I am not sure in this question:
Should the method also be documented as experimental?
where that method would be documented as experimental
Description
Documents the approach we have taken for adding experimental functionality to interfaces. We take this approach with:
receiver.Factory, may implement thereceiverprofiles.Factoryoptional interface (similar for other pipeline components)component.Hostmay implement thecomponentstatus.Reporteroptional interface.extension.Extensionmay implement the optional interfaces inextensioncapabilities.In these cases we reserve the right to change the optional, experimental parts of the underlying struct we return. You can also check whether you are using experimental functionality by checking your
go.modand seeing if you use one of these experimental modules.