DOC: add deprecation procedure #2422

Open
wants to merge 1 commit into
from

Projects

None yet

4 participants

@sciunto
Member
sciunto commented Dec 31, 2016

Closes #2357

@jni jni was assigned by sciunto Dec 31, 2016
.github/CONTRIBUTING.txt
+-----------------
+
+If the behavior of a function has to be changed, a deprecation cycle must be followed to warn users.
+Let us take an example. In version 0.12 (therefore, next release will be 0.13), we have
@emmanuelle
emmanuelle Dec 31, 2016 Member

Maybe use version n, (n+1) etc. for a more general case? (Imagine when it will be scikit-image 3.42 ;-))

.github/CONTRIBUTING.txt
+ pass
+```
+
+Here is the process for a 2 release deprecation cycle:
@emmanuelle
emmanuelle Dec 31, 2016 Member

2-release

@emmanuelle
Member

I think it's useful to add a section on how to deprecate, but as it is written now, I get the impression that the two-release deprecation cycle applies only to the value of default arguments, while other types of deprecation are possible (change the submodule where a function is found, change the return type of a function, etc.).

Maybe add a sentence at the beginning of the section, saying that any type of deprecation has to follow a 2-release cycle with warnings, and then you give the example that you have written?

@sciunto sciunto DOC: add deprecation procedure
6899dce
@sciunto
Member
sciunto commented Dec 31, 2016

Thanks @emmanuelle for the feedback. I expanded the text and fixed the rst code.

@codecov-io
codecov-io commented Dec 31, 2016 edited

Current coverage is 90.64% (diff: 100%)

No coverage report found for master at 73ac742.

Powered by Codecov. Last update 73ac742...6899dce

@jni
Contributor
jni commented Jan 1, 2017

@sciunto Even after your changes, I still feel like @emmanuelle that this is the only kind of deprecation. I would like to specify:

  • a deprecation cycle is not necessary when

    • adding a new function, or
    • adding a new keyword argument to the end of a function signature, or
    • fixing what was buggy behaviour
  • a deprecation cycle is necessary for any breaking API change, meaning a change where the function, invoked with the same arguments, would return a different result after the change. This includes:

    • changing the order of arguments or keyword arguments, or
    • adding arguments or keyword arguments to a function, or
    • changing a function's name or submodule, or
    • changing the default value of a function's arguments.

Are there others I'm forgetting?

Then, for the example, you could have some code:

def a_function(image, inplace=True):
    out = do_something(image)
    return out

to:

def a_function(image, inplace=None):
    if inplace is None:
        warn('the default value of inplace will change to `False` in version N+3')
        inplace=True
    out = do_something(image)
    return out

Though you might need to make it a bit more elaborate to make some use of inplace. =)

What do you think?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment