RE: [smila-dev] FW: Applicability of http://wiki.eclipse.org/API_Central

[<Juergen.Schumacher@xxxxxxxxxxx>]

Hi,

 

Maybe we can do easy changes now, like renaming bundles and packages from “…eilf…” to “…smila…”. But I’m not in favor of starting an API design discussion now. Let’s get our stuff into the eclipse repository and do discussions then. It should be clear that the API is provisional as the project is in incubation and there is no release. It’s also easier to get feedback from interested people outside the project (and to find interested people) once the code is accessible for everybody.

 

Cheers,

Jürgen.

 

From: smila-dev-bounces@xxxxxxxxxxx [mailto:smila-dev-bounces@xxxxxxxxxxx] On Behalf Of Thomas Menzel
Sent: Thursday, September 25, 2008 8:40 AM
To: Smila project developer mailing list
Subject: [smila-dev] FW: Applicability of http://wiki.eclipse.org/API_Central on smila/rt.* projects
Importance: High

 

hi folks,

 

plz have a read of http://wiki.eclipse.org/API_Central and its subpages.

 

then we need to discuss this topic, i.e. decide how and to what extend we want to follow these guides as it will involve quite some work in the sources.

 

question in particular: do we want to do this work before initial check-in or after?

 

BEFORE:

contra: takes even longer for sources to appear in SVN @ eclipse

 

AFTER:

contra: wore work for the committer as package renamers will cause diffs to be quickly  > 200 lines

 

Kind regards

Thomas Menzel

brox IT-Solutions GmbH

 

From: Jeff McAffer [mailto:jeff@xxxxxxxxx]
Sent: Mittwoch, 24. September 2008 23:30
To: Thomas Menzel
Cc: Markus Knauer; Smila project developer mailing list
Subject: Re: [smila-dev] Applicability of http://wiki.eclipse.org/API_Central on smila/rt.* projects

 

That is true but API is API.  as I said in my other response (sorry, didn't see this one til after sending the other), this is all about contracts.  I would be very surprised if there is anything about SMILA that is different from what we see somewhere in the Eclipse project.  A great many projects at Eclipse use these guidelines and the PDE API tooling helps people understand and follow the guidelines.

Do not take the guidelines as gospel.  If there are things you disagree with or have a better solution for, I'm sure that the folks in the architecture council and the people maintatin API central would be very happy to hear about it.

Jeff

Thomas Menzel wrote:

hi,

 

i hereby  revoke this mail as we figured this out on our own.

 

namely: to quote from http://wiki.eclipse.org/Eclipse

“The unfortunately named "Eclipse Project" is the project dedicated to producing the Eclipse SDK…”

 

hence, indeed these guides are for the top-level project and not for projects at eclipse in general.

 

Kind regards

Thomas Menzel

brox IT-Solutions GmbH

 

 

From: Jeff McAffer [mailto:jeff@xxxxxxxxx]
Sent: Mittwoch, 24. September 2008 23:25
To: Thomas Menzel
Cc: Markus Knauer; Smila project developer mailing list
Subject: Re: Applicability of http://wiki.eclipse.org/API_Central on smila/rt.* projects

 

Hey Thomas

Those guidelines are there for anyone providing API, not just for framework/core folks.  The idea is that if you are providing API then you are expecting people to call your code.  This forms a contract.  The API guidelines are all about defining that contract and evolving over time while minimizing disruption.

It is perfectly acceptable for you to put in place a set of provisional API that one day you hope to "graduate" into being real API.  This is actually to be encouraged IMHO. It is not until you actually have implementation and users that you can fully understand the design and implementation aspects of your system.

Does this mean that you can/should ignore the guidelines?  Hmmm, I don't think so. There are some good hints and directions in that doc.  They are guidelines to help you produce and maintain better API.  If you think you can serve your consumers better by doing something different, that's fine (though you should expect to explain why and how to the rest of the Eclipse community).  Note also that the guidelines do allow you to evolve your API in breaking ways.  you can have a 1.0 and a 2.0 etc.  The key is in communicating to your community what they should expect.  Is this piece of code something you think they should be calling?  Is it likely to change in the future?  How did it change since the last version?  etc.

Jeff

Thomas Menzel wrote:

Hi,

 

i have a question in regard to how strictly the guides set out @ http://wiki.eclipse.org/API_Central and its subpages are for projects that build on the eclipse framework but don’t change its existing code.

 

as far as I understand the guide it is targeted mainly for (core) framework  development of eclipse itself.

in our case we are just building on that framework and although these guides make much sense to be followed I think they also add quite an overhead – especially when a software is in its infancy and direction/design of code is still under much discussion.

 

I do understand that since we haven’t released anything yet, all our APIs are considered provisional and hence subject to change.

even though, if we want to fully implement this guide it would mean a considerable effort to change code and hence wonder, how strongly this is seen for projects like SMILA.

 

Mit freundlichen Grüßen / Kind regards

Thomas Menzel

brox IT-Solutions GmbH