You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flink.apache.org by sjk <sh...@163.com> on 2016/11/23 03:42:16 UTC
[DISCUSS] deprecated function need more detail
Hi, all
Let’s have look at Checkpointed interface below. It declared deprecated but have no detail for why, when and how replace this function. It’s 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 Scala annotation @deprecated, such as
@deprecated(message = "the reason", since = "when fully give up”)
Add this rule to customized checkstyle plugin of maven and SBT.
Best regard
-Jinkui Shi
Re: [DISCUSS] deprecated function need more detail
Posted by Ufuk Celebi <uc...@apache.org>.
There is a related checkstyle rule:
http://checkstyle.sourceforge.net/apidocs/com/puppycrawl/tools/checkstyle/checks/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+Lessons+Learned
> - Always add comments when you deprecate something
> * Add a @Deprecated annotation to the JavaDocs explaining why it was deprecated (removed, replaced, etc.)
> * Create issues with target release version for deleting deprecated interfaces
> * https://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/deprecation.html
On Mon, Mar 20, 2017 at 11:33 AM, Stephan Ewen <se...@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 <pa...@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 new
>> 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....@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 <al...@apache.org>
>> wrote:
>> >>
>> >> +1 That sounds excellent.
>> >>
>> >> On Wed, 23 Nov 2016 at 11:04 Till Rohrmann <tr...@apache.org>
>> wrote:
>> >>
>> >>> +1 for your proposal.
>> >>>
>> >>> Cheers,
>> >>> Till
>> >>>
>> >>> On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fh...@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 <sh...@163.com>:
>> >>>>
>> >>>>> Hi, all
>> >>>>>
>> >>>>> Let’s have look at Checkpointed interface below. It declared
>> deprecated
>> >>>>> but have no detail for why, when and how replace this function. It’s
>> 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 Scala
>> >>>>> annotation @deprecated, such as
>> >>>>> @deprecated(message = "the reason", since = "when fully give up”)
>> >>>>>
>> >>>>> Add this rule to customized checkstyle plugin of maven and SBT.
>> >>>>>
>> >>>>> Best regard
>> >>>>> -Jinkui Shi
>> >>>>
>> >>>
>> >
>>
>>
Re: [DISCUSS] deprecated function need more detail
Posted by Stephan Ewen <se...@apache.org>.
+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 <pa...@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 new
> 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....@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 <al...@apache.org>
> wrote:
> >>
> >> +1 That sounds excellent.
> >>
> >> On Wed, 23 Nov 2016 at 11:04 Till Rohrmann <tr...@apache.org>
> wrote:
> >>
> >>> +1 for your proposal.
> >>>
> >>> Cheers,
> >>> Till
> >>>
> >>> On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fh...@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 <sh...@163.com>:
> >>>>
> >>>>> Hi, all
> >>>>>
> >>>>> Let’s have look at Checkpointed interface below. It declared
> deprecated
> >>>>> but have no detail for why, when and how replace this function. It’s
> 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 Scala
> >>>>> annotation @deprecated, such as
> >>>>> @deprecated(message = "the reason", since = "when fully give up”)
> >>>>>
> >>>>> Add this rule to customized checkstyle plugin of maven and SBT.
> >>>>>
> >>>>> Best regard
> >>>>> -Jinkui Shi
> >>>>
> >>>
> >
>
>
Re: [DISCUSS] deprecated function need more detail
Posted by Paris Carbone <pa...@kth.se>.
+1
This should always be the norm, especially for user-facing code.
While we are at it, perhaps when someone deprecates functionality the new 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....@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 <al...@apache.org> wrote:
>>
>> +1 That sounds excellent.
>>
>> On Wed, 23 Nov 2016 at 11:04 Till Rohrmann <tr...@apache.org> wrote:
>>
>>> +1 for your proposal.
>>>
>>> Cheers,
>>> Till
>>>
>>> On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fh...@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 <sh...@163.com>:
>>>>
>>>>> Hi, all
>>>>>
>>>>> Let’s have look at Checkpointed interface below. It declared deprecated
>>>>> but have no detail for why, when and how replace this function. It’s 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 Scala
>>>>> annotation @deprecated, such as
>>>>> @deprecated(message = "the reason", since = "when fully give up”)
>>>>>
>>>>> Add this rule to customized checkstyle plugin of maven and SBT.
>>>>>
>>>>> Best regard
>>>>> -Jinkui Shi
>>>>
>>>
>
Re: [DISCUSS] deprecated function need more detail
Posted by Kostas Kloudas <k....@data-artisans.com>.
+1 and we should apply the same to all deprecated interfaces/abstract classes.
> On Nov 23, 2016, at 11:13 AM, Aljoscha Krettek <al...@apache.org> wrote:
>
> +1 That sounds excellent.
>
> On Wed, 23 Nov 2016 at 11:04 Till Rohrmann <tr...@apache.org> wrote:
>
>> +1 for your proposal.
>>
>> Cheers,
>> Till
>>
>> On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fh...@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 <sh...@163.com>:
>>>
>>>> Hi, all
>>>>
>>>> Let’s have look at Checkpointed interface below. It declared deprecated
>>>> but have no detail for why, when and how replace this function. It’s 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 Scala
>>>> annotation @deprecated, such as
>>>> @deprecated(message = "the reason", since = "when fully give up”)
>>>>
>>>> Add this rule to customized checkstyle plugin of maven and SBT.
>>>>
>>>> Best regard
>>>> -Jinkui Shi
>>>
>>
Re: [DISCUSS] deprecated function need more detail
Posted by Aljoscha Krettek <al...@apache.org>.
+1 That sounds excellent.
On Wed, 23 Nov 2016 at 11:04 Till Rohrmann <tr...@apache.org> wrote:
> +1 for your proposal.
>
> Cheers,
> Till
>
> On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fh...@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 <sh...@163.com>:
> >
> > > Hi, all
> > >
> > > Let’s have look at Checkpointed interface below. It declared deprecated
> > > but have no detail for why, when and how replace this function. It’s 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 Scala
> > > annotation @deprecated, such as
> > > @deprecated(message = "the reason", since = "when fully give up”)
> > >
> > > Add this rule to customized checkstyle plugin of maven and SBT.
> > >
> > > Best regard
> > > -Jinkui Shi
> >
>
Re: [DISCUSS] deprecated function need more detail
Posted by Till Rohrmann <tr...@apache.org>.
+1 for your proposal.
Cheers,
Till
On Wed, Nov 23, 2016 at 9:33 AM, Fabian Hueske <fh...@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 <sh...@163.com>:
>
> > Hi, all
> >
> > Let’s have look at Checkpointed interface below. It declared deprecated
> > but have no detail for why, when and how replace this function. It’s 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 Scala
> > annotation @deprecated, such as
> > @deprecated(message = "the reason", since = "when fully give up”)
> >
> > Add this rule to customized checkstyle plugin of maven and SBT.
> >
> > Best regard
> > -Jinkui Shi
>
Re: [DISCUSS] deprecated function need more detail
Posted by Fabian Hueske <fh...@gmail.com>.
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 <sh...@163.com>:
> Hi, all
>
> Let’s have look at Checkpointed interface below. It declared deprecated
> but have no detail for why, when and how replace this function. It’s 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 Scala
> annotation @deprecated, such as
> @deprecated(message = "the reason", since = "when fully give up”)
>
> Add this rule to customized checkstyle plugin of maven and SBT.
>
> Best regard
> -Jinkui Shi