I have been enjoying reading this
exchange. I was going to stay out, but when the subject turned to provisional
API I decided to take the time to share some lessons learned the hard way at
WTP. I am putting my thoughts in a blog post so that they can be more widely
read. Take a look if you are interested. You might even learn what not to do.
;)
http://lt-rider.blogspot.com/2008/10/creating-api-lessons-learned.html
Konstantin Komissarchik | Consulting
Member of Technical Staff
Phone: +1 425 201 1795 | Mobile: +1 206 898 0611
Oracle
Eclipse Tooling
411 108th Ave NE, Suite 2100
| Bellevue, WA 98004
From:
eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx
[mailto:eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx] On Behalf Of Krzysztof Daniel
Sent: Tuesday, October 21, 2008
2: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 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 :-).
--
Christopher Daniel
Technical Support Engineer
Eclipse Support Center
IBM Software Group
|
From:
|
"Oberhuber, Martin"
<Martin.Oberhuber@xxxxxxxxxxxxx>
|
|
To:
|
"E4 developer list"
<eclipse-incubator-e4-dev@xxxxxxxxxxx>
|
|
Date:
|
2008-10-20 17:43
|
|
Subject:
|
RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat
|
Hi Krzysztof,
I'm afraid that I don't understand what you want to say.
The concept of provisional API in Eclipse exists today. We
have provisional
API in releases -- For Debugging, for instance, some
provisional API to
support better customization of views has been committed in
Eclipse 3.2
and is still provisional as of today. See slide 4 of the EclipseCon
2008 DD
presentation
[1] for reference. There are even clients of
the provisional
API, but it'll be promoted to official finalized API only
once everybody
agrees that it's the right way to go.
The point to be clear about is, that provisional API will always live
in
"internal" packages [2]. Once
the API promotes to public, existing
clients of the provisional API need to be refactored to the new (non-
internal) namespace. This need for refactoring might be one
of the
reasons why some clients are reluctant to adopt provisional
API.
Perhaps we'll need to better educate clients here, that this kind of
simple rename refactoring doesn't really hurt that much. The
only
thing that it truly requires, is that clients which adopt
provisional API
need to be developed along with upcoming Eclipse releases:
When
a release makes the API public, the client needs to be
updated at
the same time as Eclipse in order to support it.
Note that as per the Eclipse Guidelines, all packages need to be
exported [3], internal or not, so
everybody can adopt them. This
seems to be exactly what you are requesting?
I agree that we need more feedback on API while it is still
provisional,
do you have any ideas for better soliciting such feedback?
[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
Cheers,
--
Martin Oberhuber, Senior Member of Technical Staff, Wind River
Target Management Project Lead, DSDP PMC
Member
http://www.eclipse.org/dsdp/tm
From:
eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx [mailto:eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx] On Behalf Of Krzysztof Daniel
Sent: Friday, October 17, 2008 4:10 PM
To: eclipse-incubator-e4-dev@xxxxxxxxxxx
Subject: [eclipse-incubator-e4-dev] Re: Avoiding Bloat
As it was said before there is a huge conflict of interests between developers
& adopters.
It is a common guideline, almost requirement, to create new API only where
there is at least one consumer. And this is a big problem. A consumer does not
have to be an expert in particular area. His requirement may be just a part of
bigger functionality, or some not-necessary-adequate point of view. More over,
he probably tries to solve his problem, and does not care about quality of
Eclipse solution (because commiters do it). So, commiters analyze, code, test,
analyze again, discuss, create some more code, and...
...API is finished when there is no more time (This is a lesson learned from
API workshop on last EclipseCon).
What happens next? New adopters arrive. Adopters of stable releases, which are
believed to be well designed and stable (and they are indeed in most cases).
The real, big feedback appears, and API evolves, but due to strict rules it is
necessary to maintain binary & contract compatibility.
I believe this is a problem - that the true feedback & adoption occurs
after the API is frozen.
Yes, I agree with some previous posts: we certainly need API evolution approach
in longer than release cycle and more feedback about provisional API.
I think it would be good to allow provisional API in Eclipse releases and make
it stable if the changes during new cycle are small enough. Of course
this solution has certain disadvantages - some code will be unstable despite it
is public. At this point we could encourage/force adopters to give us feedback,
It is for their good - the more feedback they give the more chances some
functionality will graduate to API.
We could thing also about automatic refactoring scripts or some refactoring
tools that would support upgrading to next release. Or just point to critical
places in the code and indicate what should be done.
--
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
