[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
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
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