@Restricted(Beta.class) #11
Conversation
daniel-beck
left a comment
daniel-beck
left a comment
There was a problem hiding this comment.
👍 This looks straightforward and pretty much how I imagined it would look like from previous discussion.
I wonder about the naming here though. Let me paint this bike shed a nicer shade of red:
- I'm not sure beta conveys the reason for the existence of the annotation properly. It's not scary enough. AFAIUI, calling it experimental would be more suitable (and scary).
- It's not necessarily used, just allowed.
| * or when a special flag is set in the consuming module. | ||
| * This is the property {@code useBeta} with the value {@code true}. | ||
| */ | ||
| public class Beta extends DoNotUse { |
There was a problem hiding this comment.
Would be great to add support of some info/justification text to DoNotUse so that error/warning messages can provide more details. Not a part for this PR I'd guess
There was a problem hiding this comment.
I think you can just cover that in Javadoc.
| /** | ||
| * Loads a configuration setting from the environment, such as when configured by a Maven plugin. | ||
| */ | ||
| /*@CheckForNull*/ String getProperty(String key); |
There was a problem hiding this comment.
Why is @CheckForNull commented out?
There was a problem hiding this comment.
Currently this annotation library is not a dependency.
Anyone else feel one way or another? Easy enough to change now if so. |
Well, Guava calls it this. Indeed the API might be in widespread runtime use in production. The annotation is just saying that no claims are being made about its long-term compatibility to unknown callers, at least not yet. I do not think we need to make the phrasing “scary” if your build already breaks when you try to use the API by accident; callers have been fairly warned. (BTW there is a FindBugs library for Guava’s
Of course; the way I would read <properties>
<useBeta>true</useBeta>
</properties>in someone’s POM (via jenkinsci/plugin-pom#98) is ”this plugin is, or may be, using beta APIs”. |
Yeah, and in any case, if in doubt to quickly check I guess |
|
Released as 1.14 |
6 participants
Allows you to mark some APIs are being exposed for use outside the module only to consumers which opt in to this.
@reviewbybees