API stability.

[Vladimir Ozerov]

Igniters,

We have several types of APIs:
1) Public - intended for Ignite users. E.g.: IgniteCache.
2) Private - used only by Ignite developers. E.g.: almost everything inside
"org.apache.ignite.internal".
3) Semi-private - is not expected to be used by users, but can be used by
3rd-party developers. E.g.: PluginProvider.

I'd like to propose defining "stability" for p.3 type of APIs. That is. if
someone develops Ignite extensions, he might need to know what is the
probability of breaking change of that API. Nice example of such approach
is Hadoop APIs.

The reason why I started thinking about it is "platforms" migration from
GridGain to Ignite. Currently our platforms API are far from ideal from
external developer's point of view. This was not a problem in GridGain
since the code was private, but it can become a problem in open-sourced
Ignite.
And instead of spending time on making APIs nice and clean I'd like to make
platforms work first. During this transition time it would be nice to mark
relevant APIs as "unstable" so that potential 3rd-party devs will be aware
of a risk when using them.

Thoughts?

Vladimir.

[dsetrakyan]

Vladimir,

Are you suggesting making semi-private APIs not stable? In that case, what
is the recourse for the current users?

D.

On Fri, Aug 28, 2015 at 2:55 PM, Vladimir Ozerov <[hidden email]>
wrote:

> Igniters,
>
> We have several types of APIs:
> 1) Public - intended for Ignite users. E.g.: IgniteCache.
> 2) Private - used only by Ignite developers. E.g.: almost everything inside
> "org.apache.ignite.internal".
> 3) Semi-private - is not expected to be used by users, but can be used by
> 3rd-party developers. E.g.: PluginProvider.
>
> I'd like to propose defining "stability" for p.3 type of APIs. That is. if
> someone develops Ignite extensions, he might need to know what is the
> probability of breaking change of that API. Nice example of such approach
> is Hadoop APIs.
>
> The reason why I started thinking about it is "platforms" migration from
> GridGain to Ignite. Currently our platforms API are far from ideal from
> external developer's point of view. This was not a problem in GridGain
> since the code was private, but it can become a problem in open-sourced
> Ignite.
> And instead of spending time on making APIs nice and clean I'd like to make
> platforms work first. During this transition time it would be nice to mark
> relevant APIs as "unstable" so that potential 3rd-party devs will be aware
> of a risk when using them.
>
> Thoughts?
>
> Vladimir.
>

[Gianfranco Murador]

Hi Vladimir,
I think it is better to use  public APIs for creating plugis, imho
 Regards, Gianfranco.

2015-08-28 13:55 GMT+02:00 Vladimir Ozerov <[hidden email]>:

> Igniters,
>
> We have several types of APIs:
> 1) Public - intended for Ignite users. E.g.: IgniteCache.
> 2) Private - used only by Ignite developers. E.g.: almost everything inside
> "org.apache.ignite.internal".
> 3) Semi-private - is not expected to be used by users, but can be used by
> 3rd-party developers. E.g.: PluginProvider.
>
> I'd like to propose defining "stability" for p.3 type of APIs. That is. if
> someone develops Ignite extensions, he might need to know what is the
> probability of breaking change of that API. Nice example of such approach
> is Hadoop APIs.
>
> The reason why I started thinking about it is "platforms" migration from
> GridGain to Ignite. Currently our platforms API are far from ideal from
> external developer's point of view. This was not a problem in GridGain
> since the code was private, but it can become a problem in open-sourced
> Ignite.
> And instead of spending time on making APIs nice and clean I'd like to make
> platforms work first. During this transition time it would be nice to mark
> relevant APIs as "unstable" so that potential 3rd-party devs will be aware
> of a risk when using them.
>
> Thoughts?
>
> Vladimir.
>

[Raul Kripalani-2]

On Fri, Aug 28, 2015 at 12:55 PM, Vladimir Ozerov <[hidden email]>
wrote:

> The reason why I started thinking about it is "platforms" migration from
> GridGain to Ignite. Currently our platforms API are far from ideal from
> external developer's point of view. This was not a problem in GridGain
> since the code was private, but it can become a problem in open-sourced
> Ignite.
> And instead of spending time on making APIs nice and clean I'd like to make
> platforms work first. During this transition time it would be nice to mark
> relevant APIs as "unstable" so that potential 3rd-party devs will be aware
> of a risk when using them.
>

What you describe sounds like a "mini-incubation" process inside the scope
of Ignite:

1. The contributed subproject adds new value to users.
2. Code was closed source and in an undesirable state for public display.
3. There's going to be ongoing work to amend this code in order to make it
fit for public.
4. During that time, the Ignite team warns users that the APIs may be
volatile.
5. The ultimate goal is to stabilise the "semi-private" APIs.

I don't think an API stability process needs to be defined here, after all
this scenario is transitional. The fact that user-facing APIs are evolving
is a sign that the project foundations are under heavy development.
Wouldn't it be easier to version these modules with the 0.x version series?
And then go through alpha, beta and RC stages up until version 1.0.0 –
where the APIs are expected to be stable?

Regards,

*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

[Vladimir Ozerov]

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*

Vladimir.

On Fri, Aug 28, 2015 at 4:20 PM, Dmitriy Setrakyan <[hidden email]>
wrote:

> Vladimir,
>
> Are you suggesting making semi-private APIs not stable? In that case, what
> is the recourse for the current users?
>
> D.
>
> On Fri, Aug 28, 2015 at 2:55 PM, Vladimir Ozerov <[hidden email]>
> wrote:
>
> > Igniters,
> >
> > We have several types of APIs:
> > 1) Public - intended for Ignite users. E.g.: IgniteCache.
> > 2) Private - used only by Ignite developers. E.g.: almost everything
> inside
> > "org.apache.ignite.internal".
> > 3) Semi-private - is not expected to be used by users, but can be used by
> > 3rd-party developers. E.g.: PluginProvider.
> >
> > I'd like to propose defining "stability" for p.3 type of APIs. That is.
> if
> > someone develops Ignite extensions, he might need to know what is the
> > probability of breaking change of that API. Nice example of such approach
> > is Hadoop APIs.
> >
> > The reason why I started thinking about it is "platforms" migration from
> > GridGain to Ignite. Currently our platforms API are far from ideal from
> > external developer's point of view. This was not a problem in GridGain
> > since the code was private, but it can become a problem in open-sourced
> > Ignite.
> > And instead of spending time on making APIs nice and clean I'd like to
> make
> > platforms work first. During this transition time it would be nice to
> mark
> > relevant APIs as "unstable" so that potential 3rd-party devs will be
> aware
> > of a risk when using them.
> >
> > Thoughts?
> >
> > Vladimir.
> >
>

[Vladimir Ozerov]

Raul,

Yes, separate versioning could be a solution. But 0.x and "RC" versions
usually distract users because they think that the product is not yet
stable enough to be used.in production. In our case product is fine, public
API is fine, but only extensions API is not good enough. And it can
potentially affect only very small subset of advanced users who are
developing Ignite extensions.

On Fri, Aug 28, 2015 at 4:31 PM, Raul Kripalani <[hidden email]> wrote:

> On Fri, Aug 28, 2015 at 12:55 PM, Vladimir Ozerov <[hidden email]>
> wrote:
>
> > The reason why I started thinking about it is "platforms" migration from
> > GridGain to Ignite. Currently our platforms API are far from ideal from
> > external developer's point of view. This was not a problem in GridGain
> > since the code was private, but it can become a problem in open-sourced
> > Ignite.
> > And instead of spending time on making APIs nice and clean I'd like to
> make
> > platforms work first. During this transition time it would be nice to
> mark
> > relevant APIs as "unstable" so that potential 3rd-party devs will be
> aware
> > of a risk when using them.
> >
>
> What you describe sounds like a "mini-incubation" process inside the scope
> of Ignite:
>
> 1. The contributed subproject adds new value to users.
> 2. Code was closed source and in an undesirable state for public display.
> 3. There's going to be ongoing work to amend this code in order to make it
> fit for public.
> 4. During that time, the Ignite team warns users that the APIs may be
> volatile.
> 5. The ultimate goal is to stabilise the "semi-private" APIs.
>
> I don't think an API stability process needs to be defined here, after all
> this scenario is transitional. The fact that user-facing APIs are evolving
> is a sign that the project foundations are under heavy development.
> Wouldn't it be easier to version these modules with the 0.x version series?
> And then go through alpha, beta and RC stages up until version 1.0.0 –
> where the APIs are expected to be stable?
>
> Regards,
>
> *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
>

[Konstantin Boudnik-2]

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.

Cos

> Vladimir.
>
> On Fri, Aug 28, 2015 at 4:20 PM, Dmitriy Setrakyan <[hidden email]>
> wrote:
>
> > Vladimir,
> >
> > Are you suggesting making semi-private APIs not stable? In that case, what
> > is the recourse for the current users?
> >
> > D.
> >
> > On Fri, Aug 28, 2015 at 2:55 PM, Vladimir Ozerov <[hidden email]>
> > wrote:
> >
> > > Igniters,
> > >
> > > We have several types of APIs:
> > > 1) Public - intended for Ignite users. E.g.: IgniteCache.
> > > 2) Private - used only by Ignite developers. E.g.: almost everything
> > inside
> > > "org.apache.ignite.internal".
> > > 3) Semi-private - is not expected to be used by users, but can be used by
> > > 3rd-party developers. E.g.: PluginProvider.
> > >
> > > I'd like to propose defining "stability" for p.3 type of APIs. That is.
> > if
> > > someone develops Ignite extensions, he might need to know what is the
> > > probability of breaking change of that API. Nice example of such approach
> > > is Hadoop APIs.
> > >
> > > The reason why I started thinking about it is "platforms" migration from
> > > GridGain to Ignite. Currently our platforms API are far from ideal from
> > > external developer's point of view. This was not a problem in GridGain
> > > since the code was private, but it can become a problem in open-sourced
> > > Ignite.
> > > And instead of spending time on making APIs nice and clean I'd like to
> > make
> > > platforms work first. During this transition time it would be nice to
> > mark
> > > relevant APIs as "unstable" so that potential 3rd-party devs will be
> > aware
> > > of a risk when using them.
> > >
> > > Thoughts?
> > >
> > > Vladimir.
> > >
> >

[Branko Čibej]

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.

-- Brane

[Konstantin Boudnik-2]

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

[Raul Kripalani-2]

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 <[hidden email]> 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
>
>
>
>

[Sergi]

Guys,

As I see it we have 3 types of APIs, that require strong backward
compatibility, namely the public API itself (Ignite, IgniteCache, etc...),
SPIs (IndexingSpi, DiscoverySpi, etc..) and plugin API (IgnitePlugin,
PluginContext, etc...)

None of these interfaces provide access to Ignite internals. And this is
correct design.
But if some plugin implementation chooses to utilize some private APIs of
Ignite
like GridGain does with IgniteCacheObjectProcessor it is a problem of the
implementor
to look after changes in these internal components.

As for annotations and compiler warnings - in my experience no one really
cares.

Sergi



2015-08-30 4:37 GMT+03:00 Raul Kripalani <[hidden email]>:

> 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 <[hidden email]>
> 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
> >
> >
> >
> >
>

[Vladimir Ozerov]

PluginProvider has a method "createComponent" which is used during
processor initialization. And it looks like this is the only place where
Ignite internals could be visible to plugin developers.
Lets just add detailed JavaDoc to this method warning users that
processor's API is internal stuff and subject to potentially incmpatible
changes.

On Sun, Aug 30, 2015 at 11:26 AM, Sergi Vladykin <[hidden email]>
wrote:

> Guys,
>
> As I see it we have 3 types of APIs, that require strong backward
> compatibility, namely the public API itself (Ignite, IgniteCache, etc...),
> SPIs (IndexingSpi, DiscoverySpi, etc..) and plugin API (IgnitePlugin,
> PluginContext, etc...)
>
> None of these interfaces provide access to Ignite internals. And this is
> correct design.
> But if some plugin implementation chooses to utilize some private APIs of
> Ignite
> like GridGain does with IgniteCacheObjectProcessor it is a problem of the
> implementor
> to look after changes in these internal components.
>
> As for annotations and compiler warnings - in my experience no one really
> cares.
>
> Sergi
>
>
>
> 2015-08-30 4:37 GMT+03:00 Raul Kripalani <[hidden email]>:
>
> > 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 <[hidden email]>
> > 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
> > >
> > >
> > >
> > >
> >
>

[Sergi]

Agree, documenting PluginProvider.createCompoment method must be enough
here.

Sergi

2015-08-30 13:17 GMT+03:00 Vladimir Ozerov <[hidden email]>:

> PluginProvider has a method "createComponent" which is used during
> processor initialization. And it looks like this is the only place where
> Ignite internals could be visible to plugin developers.
> Lets just add detailed JavaDoc to this method warning users that
> processor's API is internal stuff and subject to potentially incmpatible
> changes.
>
> On Sun, Aug 30, 2015 at 11:26 AM, Sergi Vladykin <[hidden email]
> >
> wrote:
>
> > Guys,
> >
> > As I see it we have 3 types of APIs, that require strong backward
> > compatibility, namely the public API itself (Ignite, IgniteCache,
> etc...),
> > SPIs (IndexingSpi, DiscoverySpi, etc..) and plugin API (IgnitePlugin,
> > PluginContext, etc...)
> >
> > None of these interfaces provide access to Ignite internals. And this is
> > correct design.
> > But if some plugin implementation chooses to utilize some private APIs of
> > Ignite
> > like GridGain does with IgniteCacheObjectProcessor it is a problem of the
> > implementor
> > to look after changes in these internal components.
> >
> > As for annotations and compiler warnings - in my experience no one really
> > cares.
> >
> > Sergi
> >
> >
> >
> > 2015-08-30 4:37 GMT+03:00 Raul Kripalani <[hidden email]>:
> >
> > > 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 <[hidden email]>
> > > 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
> > > >
> > > >
> > > >
> > > >
> > >
> >
>