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