On 02/11/2014 12:01 AM, Phil Steitz wrote: > On 2/10/14, 1:16 AM, Thomas Neidhart wrote: >> Hi, >> >> 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. >> >> 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? > > I agree with the problem statement; but I am not sure annotations > are the best or only solution. I agree with Chris that explicit > class / method or package javadoc is a good way to communicate what > we need to say and it has the advantage of being plain English, full > sentences not demanding that one learn a special vocabulary or > figure out how detached definitions apply in the context of the API.
Maybe I was not clear about that, but my intention was not to replace javadoc with annotations, but rather add them. One can always write additional javadoc to give more information about a specific topic. > IIRC, we have talked before about handling the biggest problem - > "Internal" by just doing it explicitly - i.e., o.a.c.m.internal. > That is not as ridiculous as it sounds. The only reason we *need* > to expose internal stuff is so it can be used outside the package > where it is defined. Therefore, .internal adds no import bloat. It > is also obvious and simple. > > Regarding "beta" - it seems that annotation at the class / method > level for this might end in a maintenance morass and if / when we > ever did build integration, all kinds of funny corner cases / breaks > might emerger. And for what gain, exactly, beyond just noting in > the javadoc and release notes that something is beta and subject to > change. Just slapping an annotation on a class or method does not > absolve us of the responsibility to explain why an API is unstable / > where it is going. Right, but at least it would allow us to tackle the problem from a different angle than "sorry we made a mistake here, in 3 years when we release the next major version we can fix this". > The other stuff - threadsafety, immutability, etc, seem to me to be > asking for maintenance pain and also harder than you might think to > precisely define and consistently get right. Better, IMHO to > explicitly cover this stuff, when relevant, in plain English javadoc > in the context of the API. It is not mandatory, and can be added step-by-step. We did something like this for codec, where we have written these statements (ThreadSafe or not) in the class javadoc, which is a good thing. > All that said, could be I am just being old-fashioned here and > annotations will make the world much easier for us and users, so if > others agree this is the way to go, I will try my best to help. I > definitely want to help attack the "internal" and "beta" problems > somehow, so thanks, Thomas, for bringing this to the fore. Maybe I made a mistake by mixing up two things: * changes to our release policy with Internal and Beta stuff * explicit statement of certain properties of classes like ThreadSafe For the first point, I really think we need a better solution to what we have today, but this could also be a different solution. The second one would be mainly for convenience imo. Thomas --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
