[smila-dev] Re: Applicability of http://wiki.eclipse.org/API_Central on

[Jeff McAffer <jeff@xxxxxxxxx>]

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