Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[eclipse-pmc] Provisional API guidelines

At last week's PMC call, we discussed formally adopting Jeff's proposed update to our provisional API guidelines [1]. Overall we were in agreement on the direction, but the question was raised whether additional markup and tooling were needed to distinguish provisional API from other internal packages. One approach to doing this would be additional manifest markup as described in bug 234947 [2].

I have been thinking that another approach would be a javadoc tag such as @provisional in the code itself. One advantage of this is that it puts markup directly in the code where clients are more likely to see it even if their tools are configured to ignore the warnings. It would also allow for finer-than-package granularity of provisional API, although I'm not convinced we need or want that. Conversely, manifest markup allows multiple providers of the same package to declare different intent (one could export a package provisionally, while another might declare as full API). I'm not sure if that use case makes any sense, I'm just trying to think through what advantages manifest markup has over markup in the code itself. I must be missing some reasons here but hopefully Jeff and Tom can chime in on that.



Back to the top