add section on deprecating functions to developer's guide #8546
Description
Many functions in the Sage library are deprecated, and we seem to have a standard framework in place for informing users that functions are deprecated, but there is no documentation of this in the developers' guide.
It seems like the proper way to deprecate a function is like this: if we start with
def f(x):
body of function
return something
then one should change it like so to deprecate it:
def f(x)
from sage.misc.misc import deprecation
deprecation("f() is deprecated and will be removed in a future version of Sage. Use g() instead.")
body of function
return something
One should also change doctests appropriately; if one had
sage: f(1)
'foo'
then it should get changed to
sage: f(1)
doctest:...: DeprecationWarning: f() is deprecated and will be removed in a future version of Sage. Use g() instead.
'foo'
Also, the documentation should be changed to reflect this! It's a good idea to describe what users should do instead of using the deprecated function, so that it is easy for them to change their code.
Ideally we would also have a policy about how long deprecated functions stay in Sage before being removed, but AFAIK no strong consensus on a time period or specific policy exists. If there is one, it should be put into the developer's guide!
In any case, it is probably a good idea to specify the date or Sage version in which a function was deprecated (even if it's just "March 2010") to give users an idea of how "stale" a function is and how close to removal it is.
CC: @kcrisman
Component: documentation
Reviewer: Volker Braun
Issue created by migration from https://trac.sagemath.org/ticket/8546