On Thu, 15 Dec 2016 14:31:25 +0900
IWAMOTO Toshihiro <iwam...@valinux.co.jp> wrote:
> At Wed, 14 Dec 2016 16:26:48 +0900,
> Iwase Yusuke wrote:
>>
>> Hi,
>>
>> On 2016年12月14日 15:28, FUJITA Tomonori wrote:
>> > On Mon, 12 Dec 2016 12:57:02 -0500
>> > "Victor J. Orlikowski" <v...@duke.edu> wrote:
>> >
>> >> On Mon, Dec 12, 2016, at 11:21 AM, IWAMOTO Toshihiro wrote:
>> >>> For maintaining API compatibility, having one or two release cycles of
>> >>> deprecation period, which raises warning messages if deprecated APIs
>> >>> are used, will help users. OTOH, deprecation cycles slow down
>> >>> depelopment and I am not aware of which policy ryu should take.
>> >>>
>> >>
>> >> Agreed, given that I have run afoul of this before.
>> >>
>> >> I think Fujita-San should give some guidance here, but, in my
>> >> opinion, APIs that are deprecated should probably be maintained for
>> >> *up to* 2-3 release cycles, based on degree of user impact.
>> >
>> > Thanks for the comments, guys.
>> >
>> > Seems that the project reached the stage where the developers can't
>> > break the APIs for fun. ;)
>> >
>> > As you guys suggested, having deprecation period sounds
>> > reasonable. Let's experiment 3 release cycles of deprecation period.
>> > I guess that we could have some exceptions like deleting an API that
>> > was added by mistake. Let's see how this would work.
>>
>> Just an idea...
>> for users warning, how about implementing "@deprecated" decorator
>> as following?
>>
>> File: ryu/utils.py
>>
>> def deprecated(func):
>> """
>> Decorator for marking function as deprecated.
>>
>> The decorated function should be removed in 2-3 release cycles.
>> """
>>
>> @functools.wraps(func)
>> def wrapper(*args, **kwargs):
>> LOG.warning("Called deprecated function: %s\n"
>> "This function will be remove in 2-3 release cycles.",
>> func.__name__)
>> return func(*args, **kwargs)
>>
>> return wrapper
>>
>>
>> Usage:
>> >>> from ryu.utils import deprecated
>> >>> @deprecated
>> ... def func(a, b):
>> ... print(a+b)
>> ...
>> >>> func(1, 2)
>> 3
>> Called deprecated function: func
>> This function will be remove in 2-3 release cycles.
>
> This should be ok if you are actually deprecating a function.
>
> Or, OpenStack has some decorator for semantics changes within a
> function.
>
> http://git.openstack.org/cgit/openstack/debtcollector/tree/debtcollector/updating.py
>
> Another option: for example, in this case, you could have kept the
> neighbor_add method and added neighbor_add_v2, but that's ugly.
>
> Something similar to the above listed would probably do, but it seems
> we need to devise deprecation method/procedure when a such problem
> arises in future.
Just let me make sure that I don't think that adding a new argument
like this time needs a new function. It could have kept the
compatibility; the old code works as before.
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Ryu-devel mailing list
Ryu-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/ryu-devel
