Internal classes are exposed in public API

[Andrew Mashenkov]

Hi Igniters,

Let me share some thoughts. Abstractly.

1. @Experimental API. When user see API marked as experimental usually it
is a red flag for using such API in prod
and also he can't count the API stability:
- API itself if not stable and one can have compilation issues with next
versions at least
- API semantic can be changed that can cause full API usage revision and
even rewrite code that use this API.
So, user expects API (and its implementation) is offered to user e.g. to
check if some user issues can be resolved with new API
or e.g. for review to developers can get some feedback.

2. @Deprecated API. From my point of view: Deprecation is not about "we
mark code to inform user\dev about legacy".
When user see deprecation he interpret this as a strict directive to use a
new API.
He expects the API is still workable (unless there is no notes that API is
totaly broken of course), but definitely expects a new stable API must
exist.
It is ok if old API have less capabilities or even have huge limitations.


Concrete.
1. Let's mark new metrics API as Experimental. This allow us to add any
changes in future minor releases to resolve known issues.

2. AFAIR, we have strong commitment to not change\delete old API between
minor releases.
We can't mark old metrics as deprecated regarding user expectations
described before.

Let's make old API as deprecated in *one of future minor* release, once a
new one will be considered as *stable*.
I'm not sure we even can forbid anyone to contribute to old API for now and
then until (in 3.0) it will be decided old API for removal via Voting.



On Thu, Jan 30, 2020 at 2:47 PM Maxim Muzafarov <[hidden email]> wrote:

> Igniters,
>
>
> How about to start a vote (formal) over the whole community to choose
> between these two options we have? With one caveat that veto votes are not
> applicable to this discussion. Let the whole community decide what
> direction we should move on.
>
> On Thu, 30 Jan 2020 at 14:34, Nikolay Izhikov <[hidden email]> wrote:
>
> > Hello.
> >
> > > 2. Add @IgniteExperimetnal to new API (because... see item. 1
> >
> > +1
> >
> > > 1. Remove @Deprecated from old API (because it strange to have one
> > deprecated API and second experimental API)
> >
> > -1
> >
> > I propose to update deprecation message and provide metric name for each
> > deprecated method.
> >
> > > @deprecated Use {@link JmxMetricExporterSPI} instead. Name of the
> metric
> > «io.dataregion.pageCount»
> >
> > Andrey.
> >
> > We doesn’t come to an agreement that API should be changed.
> > We should discuss the design of the Metric API and your proposals for it
> > in another thread.
> >
> > Please, avoid arguments like «this API will be 100% changed» in this
> > discussion.
> >
> > > 30 янв. 2020 г., в 14:21, Andrey Gura <[hidden email]> написал(а):
> > >
> > > From my point of view we still don't have consensus.
> > >
> > > I think we should do at least the following:
> > >
> > > 1. Remove @Deprecated from old API (because it strange to have one
> > > deprecated API and second experimental API)
> > > 2. Add @IgniteExperimetnal to new API (because... see item. 1)
> > > 3. Do not merge IGNITE-12553 (because it adds new public interface
> > > that 100% will be changed)
> > >
> > > ideally we should also:
> > >
> > > 4. Add metrics that available only via new API to the old API (because
> > > otherwise we force user interact with both API's)
> > >
> > > On Thu, Jan 30, 2020 at 12:35 PM Alexey Goncharuk
> > > <[hidden email]> wrote:
> > >>
> > >> Folks,
> > >>
> > >> I tried to re-read the whole thread and honestly got lost at the end
> :)
> > Do
> > >> we have a consensus (if yes, what are the steps?) or should we have a
> > call
> > >> as Maxim suggested?
> > >>
> > >> I think it is in our best interest to get this agreed upon fast to
> > release
> > >> AI 2.8 soon.
> >
> >
>

--
Best regards,
Andrey V. Mashenkov

[agura]

> We doesn’t come to an agreement that API should be changed.
> We should discuss the design of the Metric API and your proposals for it in another thread.
> Please, avoid arguments like «this API will be 100% changed» in this discussion.

I just explain why this item is acceptable to me. I don't discuss how
exactly something will changed, etc.

On Thu, Jan 30, 2020 at 2:34 PM Nikolay Izhikov <[hidden email]> wrote:

>
> Hello.
>
> > 2. Add @IgniteExperimetnal to new API (because... see item. 1
>
> +1
>
> > 1. Remove @Deprecated from old API (because it strange to have one deprecated API and second experimental API)
>
> -1
>
> I propose to update deprecation message and provide metric name for each deprecated method.
>
> > @deprecated Use {@link JmxMetricExporterSPI} instead. Name of the metric «io.dataregion.pageCount»
>
> Andrey.
>
> We doesn’t come to an agreement that API should be changed.
> We should discuss the design of the Metric API and your proposals for it in another thread.
>
> Please, avoid arguments like «this API will be 100% changed» in this discussion.
>
> > 30 янв. 2020 г., в 14:21, Andrey Gura <[hidden email]> написал(а):
> >
> > From my point of view we still don't have consensus.
> >
> > I think we should do at least the following:
> >
> > 1. Remove @Deprecated from old API (because it strange to have one
> > deprecated API and second experimental API)
> > 2. Add @IgniteExperimetnal to new API (because... see item. 1)
> > 3. Do not merge IGNITE-12553 (because it adds new public interface
> > that 100% will be changed)
> >
> > ideally we should also:
> >
> > 4. Add metrics that available only via new API to the old API (because
> > otherwise we force user interact with both API's)
> >
> > On Thu, Jan 30, 2020 at 12:35 PM Alexey Goncharuk
> > <[hidden email]> wrote:
> >>
> >> Folks,
> >>
> >> I tried to re-read the whole thread and honestly got lost at the end :) Do
> >> we have a consensus (if yes, what are the steps?) or should we have a call
> >> as Maxim suggested?
> >>
> >> I think it is in our best interest to get this agreed upon fast to release
> >> AI 2.8 soon.
>

[Nikita Amelchev]

Folks,

I have some experience using the new metrics API. The new format is
easy to use from the user point and approved by the community. It
provides a single metric format and one entry point. I believe that
they are able to replace existing ones. I don't see any issues with
the new metrics. The MetricExporterSpi provides the ability to easily
migrate to the new format.

So, I suggest:
1. Do NOT mark the new metric API as IgniteExperimental.
2. Mark existing metrics with Deprecated annotation with reference on
how to use and migrate to the new metrics (without reference to
internal classes).

чт, 30 янв. 2020 г. в 16:02, Andrey Gura <[hidden email]>:

>
> > We doesn’t come to an agreement that API should be changed.
> > We should discuss the design of the Metric API and your proposals for it in another thread.
> > Please, avoid arguments like «this API will be 100% changed» in this discussion.
>
> I just explain why this item is acceptable to me. I don't discuss how
> exactly something will changed, etc.
>
> On Thu, Jan 30, 2020 at 2:34 PM Nikolay Izhikov <[hidden email]> wrote:
> >
> > Hello.
> >
> > > 2. Add @IgniteExperimetnal to new API (because... see item. 1
> >
> > +1
> >
> > > 1. Remove @Deprecated from old API (because it strange to have one deprecated API and second experimental API)
> >
> > -1
> >
> > I propose to update deprecation message and provide metric name for each deprecated method.
> >
> > > @deprecated Use {@link JmxMetricExporterSPI} instead. Name of the metric «io.dataregion.pageCount»
> >
> > Andrey.
> >
> > We doesn’t come to an agreement that API should be changed.
> > We should discuss the design of the Metric API and your proposals for it in another thread.
> >
> > Please, avoid arguments like «this API will be 100% changed» in this discussion.
> >
> > > 30 янв. 2020 г., в 14:21, Andrey Gura <[hidden email]> написал(а):
> > >
> > > From my point of view we still don't have consensus.
> > >
> > > I think we should do at least the following:
> > >
> > > 1. Remove @Deprecated from old API (because it strange to have one
> > > deprecated API and second experimental API)
> > > 2. Add @IgniteExperimetnal to new API (because... see item. 1)
> > > 3. Do not merge IGNITE-12553 (because it adds new public interface
> > > that 100% will be changed)
> > >
> > > ideally we should also:
> > >
> > > 4. Add metrics that available only via new API to the old API (because
> > > otherwise we force user interact with both API's)
> > >
> > > On Thu, Jan 30, 2020 at 12:35 PM Alexey Goncharuk
> > > <[hidden email]> wrote:
> > >>
> > >> Folks,
> > >>
> > >> I tried to re-read the whole thread and honestly got lost at the end :) Do
> > >> we have a consensus (if yes, what are the steps?) or should we have a call
> > >> as Maxim suggested?
> > >>
> > >> I think it is in our best interest to get this agreed upon fast to release
> > >> AI 2.8 soon.
> >

--
Best wishes,
Amelchev Nikita

[Alexey Goncharuk]

Nikita,

Disagree here. I already gave an example in this thread of how you need to
peek into configuration in order to obtain an instance of exporter SPI
which may not necessarily be the type you need. That's why IGNITE-12553 was
created in the first place.

[dmagda]

Folks, seriously, we should deprecate an existing API only after the new
one is no longer considered experimental. There might be API and
configuration changes in the experimental API before it's announced as GA.
I would encourage us to do this properly - let's release the new APIs
labeling them as experimental for now and not label the existing as
deprecated until the new is announced as GA.

-
Denis


On Thu, Jan 30, 2020 at 9:27 AM Alexey Goncharuk <[hidden email]>
wrote:

> Nikita,
>
> Disagree here. I already gave an example in this thread of how you need to
> peek into configuration in order to obtain an instance of exporter SPI
> which may not necessarily be the type you need. That's why IGNITE-12553 was
> created in the first place.
>

[Nikolay Izhikov-2]

Alexey.

I answered to your examples and issues you provide.
But, it seems the discussion of the API and the Java code itself is not the goal of this thread anymore.

> Should we provide a way to know the number of metrics and registries in advance?

No.
If you think this is the real use-as let’s add `size` methods.
It will be the simple API *extension*.

> There is no separation on public and internal metrics

Any metric can be changed(removed) in any time.
But we will try not to do it unless we have a strong reason.

> Will we allow users to register their own metrics?

No.

> It's still not clear how a user will map old interfaces and methods to the new metric names.

We should write this information in the deprecation message.

> 30 янв. 2020 г., в 20:27, Alexey Goncharuk <[hidden email]> написал(а):
>
> Nikita,
>
> Disagree here. I already gave an example in this thread of how you need to
> peek into configuration in order to obtain an instance of exporter SPI
> which may not necessarily be the type you need. That's why IGNITE-12553 was
> created in the first place.

[agura]

I'll just repeat one thought with some changes.

There are at least two groups of people in this discussion. One group
sure that new API is complete and production ready while other group
disagree with it. Obviously we can't reach consensus about it right
now. But we can do it in the future.
At present we just can't deprecate existing API and mark new API as
experimental at the same time. So we must remove deprecation until the
consensus is reached.

Also there is the third group of people. This people aren't related
with the API, they may be don't need the API and they wait for bug
fixes and other features. It is very easy to satisfy third group: just
cut off what caused the release blocking. But it is much easier to
remove @deprecated annotations.

On Thu, Jan 30, 2020 at 8:54 PM Nikolay Izhikov <[hidden email]> wrote:

>
> Alexey.
>
> I answered to your examples and issues you provide.
> But, it seems the discussion of the API and the Java code itself is not the goal of this thread anymore.
>
> > Should we provide a way to know the number of metrics and registries in advance?
>
> No.
> If you think this is the real use-as let’s add `size` methods.
> It will be the simple API *extension*.
>
> > There is no separation on public and internal metrics
>
> Any metric can be changed(removed) in any time.
> But we will try not to do it unless we have a strong reason.
>
> > Will we allow users to register their own metrics?
>
> No.
>
> > It's still not clear how a user will map old interfaces and methods to the new metric names.
>
> We should write this information in the deprecation message.
>
> > 30 янв. 2020 г., в 20:27, Alexey Goncharuk <[hidden email]> написал(а):
> >
> > Nikita,
> >
> > Disagree here. I already gave an example in this thread of how you need to
> > peek into configuration in order to obtain an instance of exporter SPI
> > which may not necessarily be the type you need. That's why IGNITE-12553 was
> > created in the first place.
>

[Pavel Tupitsyn]

Agree with Andrey, let's remove deprecation for now and unblock the release.

On Thu, Jan 30, 2020 at 10:23 PM Andrey Gura <[hidden email]> wrote:

> I'll just repeat one thought with some changes.
>
> There are at least two groups of people in this discussion. One group
> sure that new API is complete and production ready while other group
> disagree with it. Obviously we can't reach consensus about it right
> now. But we can do it in the future.
> At present we just can't deprecate existing API and mark new API as
> experimental at the same time. So we must remove deprecation until the
> consensus is reached.
>
> Also there is the third group of people. This people aren't related
> with the API, they may be don't need the API and they wait for bug
> fixes and other features. It is very easy to satisfy third group: just
> cut off what caused the release blocking. But it is much easier to
> remove @deprecated annotations.
>
> On Thu, Jan 30, 2020 at 8:54 PM Nikolay Izhikov <[hidden email]>
> wrote:
> >
> > Alexey.
> >
> > I answered to your examples and issues you provide.
> > But, it seems the discussion of the API and the Java code itself is not
> the goal of this thread anymore.
> >
> > > Should we provide a way to know the number of metrics and registries
> in advance?
> >
> > No.
> > If you think this is the real use-as let’s add `size` methods.
> > It will be the simple API *extension*.
> >
> > > There is no separation on public and internal metrics
> >
> > Any metric can be changed(removed) in any time.
> > But we will try not to do it unless we have a strong reason.
> >
> > > Will we allow users to register their own metrics?
> >
> > No.
> >
> > > It's still not clear how a user will map old interfaces and methods to
> the new metric names.
> >
> > We should write this information in the deprecation message.
> >
> > > 30 янв. 2020 г., в 20:27, Alexey Goncharuk <[hidden email]>
> написал(а):
> > >
> > > Nikita,
> > >
> > > Disagree here. I already gave an example in this thread of how you
> need to
> > > peek into configuration in order to obtain an instance of exporter SPI
> > > which may not necessarily be the type you need. That's why
> IGNITE-12553 was
> > > created in the first place.
> >
>

[agura]

Just post here article from Oracle documentation "How and When To
Deprecate APIs" [1].

[1] https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html

On Fri, Jan 31, 2020 at 10:44 AM Pavel Tupitsyn <[hidden email]> wrote:

>
> Agree with Andrey, let's remove deprecation for now and unblock the release.
>
> On Thu, Jan 30, 2020 at 10:23 PM Andrey Gura <[hidden email]> wrote:
>
> > I'll just repeat one thought with some changes.
> >
> > There are at least two groups of people in this discussion. One group
> > sure that new API is complete and production ready while other group
> > disagree with it. Obviously we can't reach consensus about it right
> > now. But we can do it in the future.
> > At present we just can't deprecate existing API and mark new API as
> > experimental at the same time. So we must remove deprecation until the
> > consensus is reached.
> >
> > Also there is the third group of people. This people aren't related
> > with the API, they may be don't need the API and they wait for bug
> > fixes and other features. It is very easy to satisfy third group: just
> > cut off what caused the release blocking. But it is much easier to
> > remove @deprecated annotations.
> >
> > On Thu, Jan 30, 2020 at 8:54 PM Nikolay Izhikov <[hidden email]>
> > wrote:
> > >
> > > Alexey.
> > >
> > > I answered to your examples and issues you provide.
> > > But, it seems the discussion of the API and the Java code itself is not
> > the goal of this thread anymore.
> > >
> > > > Should we provide a way to know the number of metrics and registries
> > in advance?
> > >
> > > No.
> > > If you think this is the real use-as let’s add `size` methods.
> > > It will be the simple API *extension*.
> > >
> > > > There is no separation on public and internal metrics
> > >
> > > Any metric can be changed(removed) in any time.
> > > But we will try not to do it unless we have a strong reason.
> > >
> > > > Will we allow users to register their own metrics?
> > >
> > > No.
> > >
> > > > It's still not clear how a user will map old interfaces and methods to
> > the new metric names.
> > >
> > > We should write this information in the deprecation message.
> > >
> > > > 30 янв. 2020 г., в 20:27, Alexey Goncharuk <[hidden email]>
> > написал(а):
> > > >
> > > > Nikita,
> > > >
> > > > Disagree here. I already gave an example in this thread of how you
> > need to
> > > > peek into configuration in order to obtain an instance of exporter SPI
> > > > which may not necessarily be the type you need. That's why
> > IGNITE-12553 was
> > > > created in the first place.
> > >
> >

[Maxim Muzafarov]

Folks,

Let's start a vote?

On Mon, 3 Feb 2020 at 15:05, Andrey Gura <[hidden email]> wrote:

>
> Just post here article from Oracle documentation "How and When To
> Deprecate APIs" [1].
>
> [1] https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html
>
> On Fri, Jan 31, 2020 at 10:44 AM Pavel Tupitsyn <[hidden email]> wrote:
> >
> > Agree with Andrey, let's remove deprecation for now and unblock the release.
> >
> > On Thu, Jan 30, 2020 at 10:23 PM Andrey Gura <[hidden email]> wrote:
> >
> > > I'll just repeat one thought with some changes.
> > >
> > > There are at least two groups of people in this discussion. One group
> > > sure that new API is complete and production ready while other group
> > > disagree with it. Obviously we can't reach consensus about it right
> > > now. But we can do it in the future.
> > > At present we just can't deprecate existing API and mark new API as
> > > experimental at the same time. So we must remove deprecation until the
> > > consensus is reached.
> > >
> > > Also there is the third group of people. This people aren't related
> > > with the API, they may be don't need the API and they wait for bug
> > > fixes and other features. It is very easy to satisfy third group: just
> > > cut off what caused the release blocking. But it is much easier to
> > > remove @deprecated annotations.
> > >
> > > On Thu, Jan 30, 2020 at 8:54 PM Nikolay Izhikov <[hidden email]>
> > > wrote:
> > > >
> > > > Alexey.
> > > >
> > > > I answered to your examples and issues you provide.
> > > > But, it seems the discussion of the API and the Java code itself is not
> > > the goal of this thread anymore.
> > > >
> > > > > Should we provide a way to know the number of metrics and registries
> > > in advance?
> > > >
> > > > No.
> > > > If you think this is the real use-as let’s add `size` methods.
> > > > It will be the simple API *extension*.
> > > >
> > > > > There is no separation on public and internal metrics
> > > >
> > > > Any metric can be changed(removed) in any time.
> > > > But we will try not to do it unless we have a strong reason.
> > > >
> > > > > Will we allow users to register their own metrics?
> > > >
> > > > No.
> > > >
> > > > > It's still not clear how a user will map old interfaces and methods to
> > > the new metric names.
> > > >
> > > > We should write this information in the deprecation message.
> > > >
> > > > > 30 янв. 2020 г., в 20:27, Alexey Goncharuk <[hidden email]>
> > > написал(а):
> > > > >
> > > > > Nikita,
> > > > >
> > > > > Disagree here. I already gave an example in this thread of how you
> > > need to
> > > > > peek into configuration in order to obtain an instance of exporter SPI
> > > > > which may not necessarily be the type you need. That's why
> > > IGNITE-12553 was
> > > > > created in the first place.
> > > >
> > >

[dmagda]

Let's run a vote if that's the only option to come to a consensus. It will
be best if either Alex Goncharuk, Andrey Gura or Nikolay Izhikov creates a
discussion thread stating the problem and possible choices. Folks, who
would like to take over?

Generally, the vote should help us to decide how to deal with similar
situations in the future. We need to agree on how and in what circumstances
we deprecate existing APIs and engrave this on our wiki. As for this
discussion related to the new metrics framework, it should be used just as
a reference.

-
Denis


On Tue, Feb 4, 2020 at 2:38 AM Maxim Muzafarov <[hidden email]> wrote:

> Folks,
>
> Let's start a vote?
>
> On Mon, 3 Feb 2020 at 15:05, Andrey Gura <[hidden email]> wrote:
> >
> > Just post here article from Oracle documentation "How and When To
> > Deprecate APIs" [1].
> >
> > [1]
> https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html
> >
> > On Fri, Jan 31, 2020 at 10:44 AM Pavel Tupitsyn <[hidden email]>
> wrote:
> > >
> > > Agree with Andrey, let's remove deprecation for now and unblock the
> release.
> > >
> > > On Thu, Jan 30, 2020 at 10:23 PM Andrey Gura <[hidden email]> wrote:
> > >
> > > > I'll just repeat one thought with some changes.
> > > >
> > > > There are at least two groups of people in this discussion. One group
> > > > sure that new API is complete and production ready while other group
> > > > disagree with it. Obviously we can't reach consensus about it right
> > > > now. But we can do it in the future.
> > > > At present we just can't deprecate existing API and mark new API as
> > > > experimental at the same time. So we must remove deprecation until
> the
> > > > consensus is reached.
> > > >
> > > > Also there is the third group of people. This people aren't related
> > > > with the API, they may be don't need the API and they wait for bug
> > > > fixes and other features. It is very easy to satisfy third group:
> just
> > > > cut off what caused the release blocking. But it is much easier to
> > > > remove @deprecated annotations.
> > > >
> > > > On Thu, Jan 30, 2020 at 8:54 PM Nikolay Izhikov <[hidden email]
> >
> > > > wrote:
> > > > >
> > > > > Alexey.
> > > > >
> > > > > I answered to your examples and issues you provide.
> > > > > But, it seems the discussion of the API and the Java code itself
> is not
> > > > the goal of this thread anymore.
> > > > >
> > > > > > Should we provide a way to know the number of metrics and
> registries
> > > > in advance?
> > > > >
> > > > > No.
> > > > > If you think this is the real use-as let’s add `size` methods.
> > > > > It will be the simple API *extension*.
> > > > >
> > > > > > There is no separation on public and internal metrics
> > > > >
> > > > > Any metric can be changed(removed) in any time.
> > > > > But we will try not to do it unless we have a strong reason.
> > > > >
> > > > > > Will we allow users to register their own metrics?
> > > > >
> > > > > No.
> > > > >
> > > > > > It's still not clear how a user will map old interfaces and
> methods to
> > > > the new metric names.
> > > > >
> > > > > We should write this information in the deprecation message.
> > > > >
> > > > > > 30 янв. 2020 г., в 20:27, Alexey Goncharuk <
> [hidden email]>
> > > > написал(а):
> > > > > >
> > > > > > Nikita,
> > > > > >
> > > > > > Disagree here. I already gave an example in this thread of how
> you
> > > > need to
> > > > > > peek into configuration in order to obtain an instance of
> exporter SPI
> > > > > > which may not necessarily be the type you need. That's why
> > > > IGNITE-12553 was
> > > > > > created in the first place.
> > > > >
> > > >
>

[Alexey Goncharuk]

Denis,

I just realized that this vote would not be a regular Apache vote we used
to run. Usually we vote for a change to be accepted or rejected. Here, on
the other hand, we need to choose between two alternatives, and I am not
sure yet how this should be formally handled.

Dmitriy, perhaps, you can shed some light on this? Meanwhile, I'll brush up
on the voting process as well.

[Alexey Goncharuk]

Sorry for the rush, I think I got it - it's right in the voting process
[1]. This would be a vote on a procedural issue of how to handle code
deprecation.

I'll start the discussion soon, let's agree on the alternatives and then
start the vote.

[1] https://www.apache.org/foundation/voting.html

[Alexey Goncharuk]

The discussion thread is started:
http://apache-ignite-developers.2346864.n4.nabble.com/DISCUSS-Public-API-deprecation-rules-td45647.html

ср, 5 февр. 2020 г. в 12:43, Alexey Goncharuk <[hidden email]>:

> Sorry for the rush, I think I got it - it's right in the voting process
> [1]. This would be a vote on a procedural issue of how to handle code
> deprecation.
>
> I'll start the discussion soon, let's agree on the alternatives and then
> start the vote.
>
> [1] https://www.apache.org/foundation/voting.html
>