Sorry, yes I did not read your last message carefully enough. Could the runtime read the new x-?? and treat it the same as x-internal=true. A synonym for now?
Jeff
On 2010-03-18, at 4:00 PM, Thomas Watson wrote: The runtime resolver is involved to support the current x-internal/x-friends stuff in PDE. So the runtime resolver would be the ONLY thing that would need to change to get PDE to keep the same level of warnings it has today as long as we can live with the two access levels we have today (ENCOURAGED, DISCOURAGED). I am assuming provisional fall under the DISCOURAGED category at this point.
Tom
<graycol.gif>Jeff McAffer ---03/18/2010 02:51:17 PM---I agree in that people should continue to get warnings etc at least as good as they get today. So if someone removed x-interna
<ecblank.gif>
From: | <ecblank.gif>
Jeff McAffer <jeff@xxxxxxxxxxxxxxxxx> |
<ecblank.gif>
To: | <ecblank.gif>
eclipse-pmc@xxxxxxxxxxx |
<ecblank.gif>
Date: | <ecblank.gif>
03/18/2010 02:51 PM |
<ecblank.gif>
Subject: | <ecblank.gif>
Re: [eclipse-pmc] Provisional API guidelines |
I agree in that people should continue to get warnings etc at least as good as they get today. So if someone removed x-internal in favour of some new markup and then did not get warnings, that would be "a bad thing"(tm). In theory at least that would not be hard to change in PDE.
As for the runtime, I don't think there is anything for it to do if we make only allow "provisional" in the new x-access (whatever) header. The runtime should just ignore that. If there is time we can expand the new header to accomodate friends, internal, spi, ...
In the end I don't want to grease this in but have been through several iterations of trying to get the community to do something new and found it challenging.
Jeff
On 2010-03-18, at 1:41 PM, Thomas Watson wrote:
I do not think we should recommend anyone use *some* markup for provisional packages until we have put some things in place to enable the semantics behind the markup. At a minimum we need to enhance the runtime to understand the new markup. Otherwise the new directives we decide on will be completely ignored and nobody will get any warnings what so ever. Then when we do get tooling in place they will all of a sudden get lots of new warnings. We would at least need to make sure the following method returns ACCESS_DISCOURAGED I think for "provisional" packages:
org.eclipse.osgi.service.resolver.StateHelper.getAccessCode(BundleDescription, ExportPackageDescription)
Then at least folks will get the same types of warnings they would for accessing x-internal and x-friends stuff until we can get PDE to understand new codes (like ACCESS_PROVISIONAL, ACCESS_SPI etc.).
Tom
<graycol.gif>Jeff McAffer ---03/18/2010 12:03:01 PM---I was not trying to win anyone over particularly but cool. I'm glad to have *some* markup somewhere. The manifest is my natura
<ecblank.gif>
From: | <ecblank.gif>
Jeff McAffer <jeff@xxxxxxxxxxxxxxxxx> |
<ecblank.gif>
To: | <ecblank.gif>
eclipse-pmc@xxxxxxxxxxx |
<ecblank.gif>
Date: | <ecblank.gif>
03/18/2010 12:03 PM |
<ecblank.gif>
Subject: | <ecblank.gif>
Re: [eclipse-pmc] Provisional API guidelines |
I was not trying to win anyone over particularly but cool. I'm glad to have *some* markup somewhere. The manifest is my natural bias for the reasons outlined. JavaDoc is also useful.
I agree that this is not a rush but... The real target we want to hit is getting the markup in. The tooling etc can come later. At least in the guidelines it is confusing to say that provisional stuff is "x-internal" but then say that we want to have new markup to mark provisional stuff.
Bug 234947 outlines one form of manifest markup. So if we can settle on something there, it is an easy recommendation. As we have seen, it is extremely hard to change the community and mixed/changing messages just leads to confusion and frustration. I suggest that if we publish these guidelines, we solidify as much as possible.
For JavaDoc markup I am less certain. We can just say "put @provisional as necessary". Not sure if more than that is needed. The freeform text can then be replaced IMHO.
Jeff
On 2010-03-18, at 10:39 AM, John Arthorne wrote:
These points have won me over to the side of manifest markup, in particular the need for pure binary bundles to indicate their API-ness regardless of availability of javadoc. However at this point in the release cycle I'm not sure the framework and tooling teams have the time to implement new manifest markup and tooling in time for Helios.
In the end this seems like a nice thing to have, but seems separate from whether we adopt your proposed new provisional API guidelines. With both old and new guidelines, provisional API is marked x-internal. A different manifest attribute would make it a little easier for clients to distinguish their use of internals from use of provisional, presumably with the benefit that they can ignore warnings about using provisional API without ignoring warnings about other internals. This doesn't seem like an urgent enough benefit for us to push on getting this supported added for Helios.
John
The reason I liked the manifest markup is for "consistency" with the x-internal/x-friends tags which really talk about what is API and who can use it (e.g., the contract). Having said that, there is an element of history here. Traditionally the manifest markup was what was driving the tools. With the advent of API tools etc, this kind of JavaDoc markup is more interesting. Some random thoughts:
- You must be able to ship a binary bundle and indicate what parts are provisional such that I get errors when I develop code using those provisional API (assuming I say I don't want to use provisioning bits) then we have the bulk of the function we need.
- Have to talk about how to indicate provisional-ness on packages. In the package.html? Where?
- Reconcile the multiple locations for markup related to package API-ness (some in manifest, some somewhere else, ...)
Summary: I would like there to be some markup.
Jeff
On 2010-03-15, at 2:03 PM, John Arthorne wrote:
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.
John
[1] http://wiki.eclipse.org/Provisional_API_Guidelines_Update_Proposal
[2] https://bugs.eclipse.org/bugs/show_bug.cgi?id=234947_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc
|
