ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrey Gura <ag...@apache.org>
Subject Re: [DISCUSS] Public API deprecation rules
Date Thu, 06 Feb 2020 10:23:53 GMT
One comment about first choice.

The formulation has one issue from my point of view: Never deprecate
the old APIs unless the new APIs are stable *and released* without

Actually we can introduce new stable API and deprecate old API at the
same time without releasing of new API. For example
IgniteCache.withAsync() method was deprecated and new methods
xxxAsync() were added at the same time as stable alternative. In this
case we didn't collect users' feedback because negative users'
feedback about withAsync() was a driver for this change.

On Thu, Feb 6, 2020 at 6:26 AM Denis Magda <dmagda@apache.org> wrote:
> The justification and choices look crystal clear to me.
> -
> Denis
> On Wed, Feb 5, 2020 at 1:36 PM Alexey Goncharuk <agoncharuk@apache.org> wrote:
>> Igniters,
>> We would like to add some formal requirements to the API deprecation
>> process. So far the API deprecation was more like intuitive-driven which
>> recently led to some disagreement and delaying the AI 2.8 release [1][2].
>> During the discussion [1] we agreed to add an
>> annotation @IgniteExperimental [3] which marks APIs which are yet not
>> stable, dangerous, partially implemented or are allowed to be changed in a
>> future. The reason to release such APIs is to expose the APIs to users and
>> collect feedback on the usability and possible bugs.
>> The argument we did not manage to resolve is whether we are allowed to
>> deprecate the old APIs _before_ the new ones get stable and get released
>> without @IgniteExperimental annotation. We decided to resolve the
>> uncertainty with a vote.
>> The vote we are going to have is reduced to two choices so far:
>>  * Never deprecate the old APIs unless the new APIs are stable and released
>> without @IgniteExperimental. The old APIs javadoc may be updated with a
>> reference to new APIs to encourage users to evaluate new APIs
>>  * Allow to deprecate the old APIs even when new APIs are marked
>> with @IgniteExperimental to explicitly notify users that the new APIs are
>> available
>> Nikolay, Andrey, please let us know if we should correct the choices
>> articulation or add another option for the vote.
>> --AG
>> [1]
>> http://apache-ignite-developers.2346864.n4.nabble.com/Internal-classes-are-exposed-in-public-API-td45146.html
>> [2]
>> http://apache-ignite-developers.2346864.n4.nabble.com/Internal-classes-are-exposed-in-public-API-td45146.html
>> [3] https://issues.apache.org/jira/browse/IGNITE-12559

View raw message