Mailing-List: contact dev-help@flink.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@flink.apache.org
MIME-Version: 1.0
In-Reply-To: <CANC1h_tZXGgTedE7K2C0feHRZRJpCC5hniL9NUXt0CDevy7dXQ@mail.gmail.com>
References: <B96A3743-8D72-4CF7-AB74-54F449B44CEC@163.com> <CAAdrtT1CJpi_OmGbutnZFx-g2d1g_VUPT9zx5jqBbu2gcpGftA@mail.gmail.com>
 <CAC27z=NG5gG1-is6BEU3+th=L1OdVk8VP7S=vksg37VGvp3i9Q@mail.gmail.com>
 <CANMXwW0RFtbYopL3daS1iu6UXah1iRKRjRvm_47GpQ5fHBW75Q@mail.gmail.com>
 <B43D5771-2A6E-4C27-B0A7-26567C5D9E53@data-artisans.com> <86AB2F32-67EB-455E-98FB-41B431F7C11E@kth.se>
 <CANC1h_tZXGgTedE7K2C0feHRZRJpCC5hniL9NUXt0CDevy7dXQ@mail.gmail.com>
From: Ufuk Celebi <uce@apache.org>
Date: Mon, 20 Mar 2017 11:42:13 +0100
Message-ID: <CAKiyyaEzYC+sVNd3vpYt4juL22+sAAQWsThqMmDzNhODf9nLHw@mail.gmail.com>
Subject: Re: [DISCUSS] deprecated function need more detail
To: dev@flink.apache.org
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
archived-at: Mon, 20 Mar 2017 10:42:57 -0000

There is a related checkstyle rule:
http://checkstyle.sourceforge.net/apidocs/com/puppycrawl/tools/checkstyle/c=
hecks/annotation/MissingDeprecatedCheck.html

Added a JIRA for adding it here:
https://issues.apache.org/jira/browse/FLINK-6127

We actually wrote this down in our hidden Wiki at
https://cwiki.apache.org/confluence/display/FLINK/Best+Practices+and+Lesson=
s+Learned

> - Always add comments when you deprecate something
> * Add a @Deprecated annotation to the JavaDocs explaining why it was depr=
ecated (removed, replaced, etc.)
> * Create issues with target release version for deleting deprecated inter=
faces
> * https://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/dep=
recation.html


On Mon, Mar 20, 2017 at 11:33 AM, Stephan Ewen <sewen@apache.org> wrote:
> +1
>
> I think we actually had the same discussion already a while back. Let's
> bring it back to everyone's awareness!
>
>
>
> On Wed, Nov 23, 2016 at 12:09 PM, Paris Carbone <parisc@kth.se> wrote:
>
>> +1
>>
>> This should always be the norm, especially for user-facing code.
>>
>> While we are at it, perhaps when someone deprecates functionality the ne=
w
>> alternative should also be replaced right away.
>> E.g. Checkpointed is deprecated but all state management tests are
>> actually using this alternative.
>>
>> cheers
>> Paris
>>
>>
>> > On 23 Nov 2016, at 11:21, Kostas Kloudas <k.kloudas@data-artisans.com>
>> wrote:
>> >
>> > +1 and we should apply the same to all deprecated interfaces/abstract
>> classes.
>> >
>> >> On Nov 23, 2016, at 11:13 AM, Aljoscha Krettek <aljoscha@apache.org>
>> wrote:
>> >>
>> >> +1 That sounds excellent.
>> >>
>> >> On Wed, 23 Nov 2016 at 11:04 Till Rohrmann <trohrmann@apache.org>
>> wrote:
>> >>
>> >>> +1 for your proposal.
>> >>>
>> >>> Cheers,
>> >>> Till
>> >>>
>> >>> On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fhueske@gmail.com>
>> wrote:
>> >>>
>> >>>> I agree on this one.
>> >>>> Whenever we deprecate a method or a feature we should add a comment
>> that
>> >>>> explains the new API or why the feature was removed without
>> replacement.
>> >>>>
>> >>>> Enforcing this information through checkstyle makes sense as well,
>> IMO.
>> >>>>
>> >>>> Cheers, Fabian
>> >>>>
>> >>>> 2016-11-23 4:42 GMT+01:00 sjk <shijinkui666@163.com>:
>> >>>>
>> >>>>> Hi, all
>> >>>>>
>> >>>>> Let=E2=80=99s have look at Checkpointed interface below. It declar=
ed
>> deprecated
>> >>>>> but have no detail for why, when and how replace this function. It=
=E2=80=99s
>> a
>> >>>> big
>> >>>>> trouble for the users.
>> >>>>>
>> >>>>> @Deprecated
>> >>>>> @PublicEvolving
>> >>>>> public interface Checkpointed<T extends Serializable> extends
>> >>>>> CheckpointedRestoring<T> {
>> >>>>>
>> >>>>>
>> >>>>> I think we should have more detail: when give up, who replace it, =
why
>> >>>>> deprecated.
>> >>>>>
>> >>>>> For Java code, add detail  deprecated reason in code annotations.
>> >>>>> For Scala code, replace Java annotation  @Deprecated(,,) with Scal=
a
>> >>>>> annotation @deprecated, such as
>> >>>>> @deprecated(message =3D "the reason", since =3D "when fully give u=
p=E2=80=9D)
>> >>>>>
>> >>>>> Add this rule to customized checkstyle plugin of maven and SBT.
>> >>>>>
>> >>>>> Best regard
>> >>>>> -Jinkui Shi
>> >>>>
>> >>>
>> >
>>
>>