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 @IgniteExperimental.
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 <dma...@apache.org> wrote: > > The justification and choices look crystal clear to me. > > - > Denis > > > On Wed, Feb 5, 2020 at 1:36 PM Alexey Goncharuk <agoncha...@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
