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
