RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

> As said, I'd like to file
two AC bugs to further discuss it (one for the process, the other for the
naming policy), if we get some consensus that it's a topic worth > discussing.
What do you think, John?

Definitely worth discussing. I'm less convinced
that the discussion will lead to consensus, but it's still worth bringing
up. One valid issue brought up in the past is that projects in their early
stages face very different demands and community pressures than mature
projects, so there isn't necessarily a one-size-fits-all policy. But this
makes it an ideal discussion on the arch council where there is representation
from all projects.

John

"Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>
Sent by: eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx

10/21/2008 10:20 AM

Please respond to
E4 developer list <eclipse-incubator-e4-dev@xxxxxxxxxxx>

To	"E4 developer list" <eclipse-incubator-e4-dev@xxxxxxxxxxx>
cc
Subject	RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat

> I'm happy to clarify it, but I don't
understand what is unclear or illogical about it.

 
I think it's a matter of defining
what "provional API" means. In my opinion,
it could also be named "API
under construction". Given that the thing under
construction was not promoted
into API at some release, does not mean
that all workers are pulled off
the construction area and it's left in its
current non-finished state forever.
It also doesn't mean that the process
of soliciting community input
is stopped at this point and the area
turns into something internal
that only committers should care about.
 
I'm really trying to come up with
a process for this API construction 
work that helps soliciting input,
by helping early adopters at all stages,
clarifying (and unifying) the
policies based on what we think are best
practices.
 
From that point of view, I'd think
that when the team (committers + 
community) cannot agree on freezing
some API at one point, they
should likely continue to work
on things until they are happy. In
other words, provisional API may
remain -- in the state that a
project is using for provisional
API, which is "internal.provisional"
packages for the Eclipse project,
with the promise (or rather
non-promise) to change it at any
time without notice.
 
As said, I'd like to file two
AC bugs to further discuss it (one
for the process, the other for
the naming policy), if we get 
some consensus that it's a topic
worth discussing. What 
do you think, John?
 
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 John
Arthorne
Sent: Tuesday, October 21, 2008 4:10 PM
To: E4 developer list
Subject: RE: [eclipse-incubator-e4-dev] Re: Avoiding Bloat


The difference in policy between [2] and [4] is because those documents
are written by different people for different audiences. [2] was written
by me at the request of the Eclipse Project PMC to codify our guidelines
(which had been around much longer but never written down). Those guidelines
were only intended to be for the Eclipse top-level project. I don't know
the history of document [4], but I suspect it was written by the Foundation
with the intent to provide guidelines that all top-level projects could
live with. I don't know what projects follow them, but I know some projects
put provisional API in non-internal packages. There was never broad agreement
across projects on this point which likely led to that compromise table
with several different flavours of pseudo-API. 

> [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?

API is primarily a contract that implies long term support and a promise
of compatibility across releases. If something is provisional and subject
to change, then there is no implied support or compatibility, so it is
not API. This doesn't mean it can't become API at some point in the future.
We certainly do have packages with "*.internal.provisional.*"
in one release, which is then validated and polished into real API in the
next release. But, at the time the package is "internal.provisional",
it is internal code and subject to change. I'm happy to clarify it, but
I don't understand what is unclear or illogical about it.

John

"Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>
Sent by: eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx

10/21/2008 07:59 AM

Please respond to
E4 developer list <eclipse-incubator-e4-dev@xxxxxxxxxxx>

To	"E4 developer list" <eclipse-incubator-e4-dev@xxxxxxxxxxx>
cc
Subject	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

• 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: eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx
[mailto:eclipse-incubator-e4-dev-bounces@xxxxxxxxxxx] 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
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

_______________________________________________
eclipse-incubator-e4-dev mailing list
eclipse-incubator-e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-incubator-e4-dev
_______________________________________________
eclipse-incubator-e4-dev mailing list
eclipse-incubator-e4-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-incubator-e4-dev