Implement deprecation cycle

[nrweir]

copied from scikit-image's CONTRIBUTING.txt:

Deprecation cycle

If the behavior of the library has to be changed, a deprecation cycle must be
followed to warn users.

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.
Usually, our policy is to put in place a deprecation cycle over two releases.

For the sake of illustration, we consider the modification of a default value in
a function signature. In version N (therefore, next release will be N+1), we
have

.. code-block:: python

def a_function(image, rescale=True):
out = do_something(image, rescale=rescale)
return out
that has to be changed to

.. code-block:: python

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

.. code-block:: python

def a_function(image, rescale=False):
out = do_something(image, rescale=rescale)
return out
Here is the process for a 2-release deprecation cycle:

In the signature, set default to None, and modify the docstring to specify
that it's True.
In the function, if rescale is set to None, set to True and warn that the
default will change to False in version N+3.
In doc/release/release_dev.rst, under deprecations, add "In
a_function, the rescale argument will default to False in N+3."
In TODO.txt, create an item in the section related to version N+3 and write
"change rescale default to False in a_function".
Note that the 2-release deprecation cycle is not a strict rule and in some
cases, the developers can agree on a different procedure upon justification
(like when we can't detect the change, or it involves moving or deleting an
entire function for example).