Hi Thomas, If this is only for documentary purposes, it seems a bit strange in my mind. Wouldn't a comment at the header serve the same purpose?
-Chris On Mon, Feb 10, 2014 at 7:03 AM, luc <[email protected]> wrote: > Le 2014-02-10 10:16, Thomas Neidhart a écrit : > >> Hi, >> > > Hi Thomas, > > > >> this is an issue I was thinking about for some time now, and it is quite >> some recurrent theme that we face in Commons. >> >> Considering our release practice, it is actually quite hard to come up >> with >> new features as the API is more or less fixed once it has been included. >> Ideally, this could or should be handled with alpha/beta releases were we >> gather feedback on a new API, but due to limited resources this does not >> seem feasible. From experience in Math we also see that when we want to >> extend an existing API for further uses, it is sometimes impossible to be >> backwards compatible simply because the original API did not foresee such >> things, which is quite normal I guess. >> >> Thus, I would like to discuss another approach. Add certain annotations to >> the code that clearly mark the mark the current state of a class/type and >> which allows us to break compatibility for such classes even in minor >> releases. >> > > Would these annotations only be used as documentation or would there be > some > tools for users? > > Luc > > > >> As a first step I would foresee the following annotations: >> >> * Internal: Only for internal use, no guarantee about BC or may even be >> removed without warning >> * Beta: New API, may be changed in minor releases after gathering >> feedback >> from the community >> >> Additionally, I would like to introduce also the annotations from the >> jcip ( >> jcip.net). I do not know if we can add them as dependency, but we could >> also add them ourselves. IMO this would be of great benefit to our users >> if >> it is clear if a certain class is Immutable, ThreadSafe or Not and one >> does >> not have to analyze the source code to assert him/herself. >> >> I created a ticket for this, and started with two annotations so far: >> >> https://issues.apache.org/jira/browse/MATH-1098 >> >> So what do you think about that? >> >> Thomas >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- Chris
