commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Neidhart <>
Subject [math] Annotations
Date Mon, 10 Feb 2014 09:16:53 GMT

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

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 ( 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:

So what do you think about that?


  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message