Re: [cosmos-dev] Question about provisional APIs

[Valentina Popescu <popescu@xxxxxxxxxx>]

It would be much easier if we could
find the minutes from the meeting where this decision was made.


Thank you,
Valentina Popescu
IBM Toronto Labs
Phone:  (905)413-2412         (tie-line  969)
Fax: (905) 413-4850

"Ali Mehregani" <ali.mehregani@xxxxxxxxx>
Sent by: cosmos-dev-bounces@xxxxxxxxxxx

01/09/2008 04:17 PM

Please respond to
Cosmos Dev <cosmos-dev@xxxxxxxxxxx>

To	"Cosmos Dev" <cosmos-dev@xxxxxxxxxxx>
cc
Subject	Re: [cosmos-dev] Question about provisional APIs

>From what I recall, there was an agreement that requiring
the package names to contain 'provisional' will cause code breakage when
APIs transitioned from provisional to public.  I do agree that there
are pros and cons to each approach but we should go with what the majority
agreed on during the F2F.  The annotation is added as part of the
class comment, so it should also work with _javascript_s. 

David,
We should go as far as annotating classes.  Adding annotation to individual
methods is too much maintenance.  Marking a class as provisional is
an all or nothing case.  i.e. there is no such thing as a class being
half provisional. 

Mark or project leads, please speak up if you see something fundamentally
wrong with this approach.
Thanks.


On Jan 9, 2008 2:38 PM, Sheldon Lee-Loy <
sleeloy@xxxxxxxxxx> wrote:

Did we agree on using java annotations?  For some reason I can't recall
this.   

Java annotations only works with java files.  We have _javascript_ files
that can be extended as well.  I've been encoding the word 'provisional'
in java and _javascript_ package names.   

I think this is better than using java annotation.  First it's easier
to determine if code is using internal, public or provisional apis by glancing
at the import statements.  Second encodiing works with _javascript_
files.   

Thanks,

Sheldon
______________________________________
Sheldon Lee-Loy
Tivoli Autonomic Computing, IBM Toronto Lab
email: sleeloy@xxxxxxxxxx
phone: 905.413.2610

David Whiteman <David_Whiteman@xxxxxxxxxx>
Sent by: cosmos-dev-bounces@xxxxxxxxxxx

01/09/2008 02:05 PM

Please respond to
Cosmos Dev <cosmos-dev@xxxxxxxxxxx>

To	cosmos-dev@xxxxxxxxxxx
cc
Subject	[cosmos-dev] Question about provisional APIs

At the last F2F, we discussed the COSMOS dev process, and in particular
how to denote provisional APIs.  It was decided that we would use
Java annotations instead of encoding "provisional" in the package
name.  I'm trying to remember the details of what we decided.  Did
we simply decide to use the approach documented here in the TPTP API Contract
document for stable provisional APIs for all of our provisional APIs?

http://www.eclipse.org/tptp/home/documents/process/development/api_contract.html

If so, is the following wording sufficient for putting into our own dev
process: 

Provisional API is API that can change, but is unlikely to change in the
next release. Such code has the @provisional tag in the Javadoc. Provisional
API is solid but is not public for any number of reasons: the implementation
may fluctuate, the function's quality isn't as high as we'd like it to
be yet, ports to other platforms may be needed, etc. 

One question I have is whether we put the @provisional tag in every method
comment, or just the class comment, or both?  We often have entire
interfaces that are considered provisional, so I didn't know where it should
be best indicated. 

David_______________________________________________
cosmos-dev mailing list
cosmos-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cosmos-dev


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




-- 
Ali Mehregani
COSMOS Project
http://www.eclipse.org/cosmos/
_______________________________________________
cosmos-dev mailing list
cosmos-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cosmos-dev