Add experimental annotation to SPI developer guide #14021
Conversation
| Marking as experimental | ||
| ----------------------- | ||
|
|
||
| If your SPI is experimental or still a work in progress, you can use the |
There was a problem hiding this comment.
This guide is about building plugins that implement the SPI, not provide new SPIs. I think this paragraph should be rephrased to explain that using an SPI marked as experimental, the developer should expect it to change in future releases and be ready to adjust to these changes.
There was a problem hiding this comment.
We should say something like
SPI elements that are annotated with `@Experimental` are subject to change without any notice, deprecation period.
Their signatures or semantics may change, and a compilation error is not guaranteed.
Use at your own risk.
Or, we can copy more words from https://github.com/google/guava/blob/2b55799273247661132f999d66943c6adb6ccc35/guava/src/com/google/common/annotations/Beta.java#L23-L35
There was a problem hiding this comment.
BTW Experimental already has a javadoc saying what it is and after #14033 it will be revealed in javadocs. Do we need to mention it here at all?
There was a problem hiding this comment.
I think it's worth it, we don't publish Javadocs anywhere, right?
There was a problem hiding this comment.
The information contained in javadoc is more important that one in this doc.
I do assume it's already visible to SPI users one way or the other. If not, we have a bigger problem that supplementing this (nice) docs with more information.
Description
Adding docs on the Experimental annotation in SPI dev guide. Resolves #13520
Non-technical explanation
Docs.
Release notes
(x) This is not user-visible and no release notes are required.
( ) Release notes are required, please propose a release note for me.
( ) Release notes are required, with the following suggested text: