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
*
Provisional API can be removed at any milestone build, provided
that
it has been marked @deprecated in the previous milestone build.
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
http://www.eclipse.org/dsdp/tm
________________________________
From: [EMAIL PROTECTED]
[mailto:[EMAIL PROTECTED] On Behalf Of
Krzysztof Daniel
Sent: Tuesday, October 21, 2008 11:29 AM
To: E4 developer list
Subject: RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat
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
<http://www.eclipse.org/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
<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/index.php?page=sub/&id=45>
http://www.eclipsecon.org/2008/sub/attachments/Device_Debugging_Project_
Update.pdf
<http://www.eclipsecon.org/2008/sub/attachments/Device_Debugging_Project
_Update.pdf>
[2] http://wiki.eclipse.org/Provisional_API_Guidelines
<http://wiki.eclipse.org/Provisional_API_Guidelines>
[3] http://wiki.eclipse.org/Export-Package
<http://wiki.eclipse.org/Export-Package>
--
Christopher Daniel
Technical Support Engineer
Eclipse Support Center
IBM Software Group
_______________________________________________
eclipse-incubator-e4-dev mailing list
[email protected]
https://dev.eclipse.org/mailman/listinfo/eclipse-incubator-e4-dev
<https://dev.eclipse.org/mailman/listinfo/eclipse-incubator-e4-dev>
_______________________________________________
eclipse-incubator-e4-dev mailing list
[email protected]
https://dev.eclipse.org/mailman/listinfo/eclipse-incubator-e4-dev
