Is it really necessary for the user to be reminded on every compilation? If I understand correctly, the types of annotation you want to introduce are informative – not necessarily prompting to immediate action like a @Deprecated annotation. The latter inevitably ends in a removal and consequent API breakage. But in the circumstances where @Evolving is applicable, there's no immediate action the user could take: they just have to live with the transitional nature, and the API may not even change ever. So there's no point in nagging them with every build, IMHO.
Just making it part of Javadoc should be enough, to raise awareness about a possible rocky road ahead... *Raúl Kripalani* Apache Camel PMC Member & Committer | Enterprise Architect, Open Source Integration specialist http://about.me/raulkripalani | http://www.linkedin.com/in/raulkripalani http://blog.raulkr.net | twitter: @raulvk On Sun, Aug 30, 2015 at 2:19 AM, Konstantin Boudnik <c...@apache.org> wrote: > On Sat, Aug 29, 2015 at 11:07PM, Branko Čibej wrote: > > On 29.08.2015 00:06, Konstantin Boudnik wrote: > > > On Fri, Aug 28, 2015 at 05:14PM, Vladimir Ozerov wrote: > > >> Dima, > > >> > > >> I'm not suggesting doing this, they are already not stable. For > example, > > >> take a look at IgniteCacheObjectProcessor. This is a component which > can be > > >> injected through plugins, thus it is "semi-public". However, it is > under > > >> heavy changes and if some unlucky guy is to implement a plugin using > this > > >> processor, he will face compilation errors with each new Ignite > release. > > >> > > >> My suggestion is to define policies for things like that. One of > possible > > >> solutions - is to annotate APIs so that developers are aware of > potential > > >> problems. > > >> > > >> One more example from Hadoop: > > >> 1) org.apache.hadoop.fs.FileSystem: @Public, @Stable > > >> 2) org.apache.hadoop.fs.AbstractFileSystem: @Public, *@Evolving* > > > I think having those annotations aren't making developers more aware > about > > > potential compatibility problems, nor enforce any kind of policy > mechanism > > > around API compatibility. There's a plenty of examples in Hadoop (YARN > in 2.4 > > > and some other stuff before it) where incompatible changes were > introduced in > > > minor releases and had to be quickly corrected in a consequent patch > release. > > > > > > What these annotations might help with is to quickly settle the > argument that > > > certain APIs shouldn't have been used in the first place, because they > were > > > @Evolving or otherwise. It's more like a UML diagram: if something > goes wrong > > > ppl have a common ground to find our who has screwed up and why; but it > > > doesn't prevent the screw-up itself. > > > > > > Perhaps relying on public APIs as the only fully approved for 3rd party > > > software developers is the only recourse in this case. > > > > There's nothing inherently wrong with publishing experimental public > > APIs, as long as they're clearly marked as such. Subversion does that, > > on rare occasions; we don't loose sleep over people writing code against > > those APIs, they get ample warning at compile time and in the docs. Once > > the APIs are finalized, we remove the experimental annotation. > > I agree in principle. However, having some mechanism to enforce the > warning on > the experimental APIs is very handy. I think in Java something like this > https://github.com/pushtorefresh/javac-warning-annotation > could you be used to generate compile-time warnings. It is conveniently > under > ASL2 and has its artifacts on maven central. > > Cos > > > >
