[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat
|
Hello Krzysztof,
[2] After the API freeze, there is really no such
thing as "provisional API". Either it is complete and committed platform API, or
it is internal code.
Hm... I know this passage and agree that it is not in line
with my current
thinking. Perhaps Boris, John or McQ could explain? For me,
it seems
OK to have provisional API live in "internal" packages even
across multiple
releases.
Just assuming that some provisional API was
proposed and just didn't get
ready in time. This can't be a reason for never
ever working on promoting
it in the future? The passage cited does not seem
logical, and I'm wondering
if it could be rewritten for
clarification.
[2] Technically, a provisional API can change
arbitrarily or be removed at any time without notice.
Yes, I agree that this doesn't sound friendly for
provisional API adopters at
all, and does not help encouraging early
adoption. I think that we should
consider more helpful policies, such as
Discussing such policies
for provisional API (making a recommendation for
all Eclipse projects to adopt them) would be a good topic
for the Architecture
Council. The goal of the
discussion should be increasing early adoption and
feedback for provisional
API. I'd just like to get some initial feedback on this
idea before I file a bug
on the Architecture Council component (well in fact
anybody can file such a bug).
Note
the public package in the provisional API. It is contradictory to the
[2]
I assume that in the
cited table, the "public" means that the packages are
exported and publicly
visible (which is recommended for EVERY package
including those that have
an "internal" segment in their package name. In
this light, this isn't a
contradiction.
new API is released as provisional in release X and then
hardened into platform APIs in release X+1.
Well that also seems too
blindly following a principle. The API is ready when
it is ready and shouldn't
be promoted just because it's old. A better description
should be
"We have a constant project plan item to work on
hardening API that has
been introduced as
provisional in the previous release".
which says that it's an
item to work on, regardless of to what extent the goal
is reached.
Provisional API
should be in public packages and has clear javadoc that would:
But
that's exactly what's happening. The packages are
public today. They
just
have some "internal" segment in their name. Perhaps what you're
missing
is
some clear indication in the package name that separates provisional
API
from
all the wade of other internal stuff. That's something worth
discussing
and
specifying. As far as I know, some projects have adopted a naming
scheme
like
org.eclipse.platform.internal.core.provisional.api
which
is lengthy but does provide the requested separation. I'm against
placing
provisional API into non-internal packages since it
would way too easily be
taken
for hardened. Although some API Tooling tags could perhaps help
here.
Coming
up with a generally recommended naming scheme for
provisional
API
might be worth another bug on the Architecture Council component
for
discussion.
Thanks
for bringing up the issue and being persistent. I think that we're
touching on some important issues here, and I'm looking
forward to the
followup discussions.
Cheers,
--
Martin Oberhuber, Senior Member of Technical
Staff, Wind River
Target Management Project
Lead, DSDP PMC Member
Hi Martin,
The sources you have mentioned also say:
[2] After the API freeze, there
is really no such thing as "provisional API". Either it is complete and
committed platform API, or it is internal code.
Moreover it reads:
[2] Technically, a provisional API can change
arbitrarily or be removed at any time without notice.
I believe that this document indicates that there is
strong "API"-"Internal" division after the release (and maybe
this is only my interpretation).
In the [4] I have found interesting table:
|
Specification
|
Test Suite
|
Implementation
|
Clients
|
Support
Promise
|
Package
|
Platform API
|
yes
|
yes
|
yes
|
yes
|
yes
|
public
|
Provisional
|
yes
|
yes
|
yes
|
yes
|
not
quite
|
public |
The table is bigger of course, but only those two cases
are important for us. Note the public package in the provisional API.
It is contradictory to the [2] unless provisional API becomes API after every
release.
I am happy to see that
someone is already using provisional API independent from release cycle, even
happier that The TPTP project uses Provisional
APIs for all new API introductions: the new API is released as provisional in
release X and then hardened into platform APIs in release X+1. (4)
Maybe it would be good to ask TPTP team
how this approach works in real environment?
What I'd expect from Eclipse is to adopt slightly
modified TPTP strategy - harden provisional API when it has not changed for
one development cycle. Provisional API should be in public packages and has
clear javadoc that would:
* warn the
user that the API *may* change.
*
encourage the user to register to particular mailing list/watch some wiki
pages
On the other hand we could
think about support from API tools, that would throw warnings/errors when the
client access provisional API, and about completely new tool that would ask
the user to register on mailing list, display messages from developer
etc.
[4] http://wiki.eclipse.org/Eclipse_Quality
Example:
Commiter A creates:
package
org.eclipse.component;
/**
* This is provisional API. It is
believed to be stable, but still may change. For your own good subscribe to
the list component-dev-provisional to be notified about changes.
* @provisional
* @since 3.5
*/
public interface
IInterface{
public void method1();
public void method2();
}
Now some client
implements that interface. It is warned (by API tools) and prompted to
register to the newsgroup. During the development cycle we may ask
clients if they got what they expected and if we can do anything
better.
Eclipse 3.5 is released. A
lot of people uses that interface, and it appears that third method is
necessary. So the commiter adds method3(), posts to concrete mailing list and
all customers are informed about compatibility breaking change. Also steps
necessary to adapt new method are described (and in the future maybe some more
advanced refactoring scripts).
Eclipse 3.6 is released with that change, than 3.7 without change, so
the @provisional tag should be deleted and... no refactoring at that point
:-).
I hope that my vision is
easier to understand now :-).
[1] EclipseCon 2008 Device Debugging (DD) Update
http://www.eclipsecon.org/2008/index.php?page=sub/&id=45
http://www.eclipsecon.org/2008/sub/attachments/Device_Debugging_Project_Update.pdf
[2]
http://wiki.eclipse.org/Provisional_API_Guidelines
[3]
http://wiki.eclipse.org/Export-Package
--
Christopher Daniel
Technical Support Engineer
Eclipse Support Center
IBM Software Group _______________________________________________
eclipse-incubator-e4-dev
mailing list
eclipse-incubator-e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-incubator-e4-dev