#8546: add section on deprecating functions to developer's guide
-----------------------------+----------------------------------------------
Reporter: ddrake | Owner: mvngu
Type: enhancement | Status: new
Priority: major | Milestone: sage-4.3.4
Component: documentation | Keywords:
Author: | Upstream: N/A
Reviewer: | Merged:
Work_issues: |
-----------------------------+----------------------------------------------
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.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/8546>
Sage <http://www.sagemath.org>
Sage: Creating a Viable Open Source Alternative to Magma, Maple, Mathematica,
and MATLAB
--
You received this message because you are subscribed to the Google Groups
"sage-trac" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sage-trac?hl=en.
