Opened 10 years ago
Closed 8 years ago
#8546 closed enhancement (duplicate)
add section on deprecating functions to developer's guide
Reported by: | ddrake | Owned by: | mvngu |
---|---|---|---|
Priority: | major | Milestone: | sage-duplicate/invalid/wontfix |
Component: | documentation | Keywords: | |
Cc: | kcrisman | Merged in: | |
Authors: | Reviewers: | Volker Braun | |
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
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.
Change History (7)
comment:1 Changed 10 years ago by
comment:2 Changed 10 years ago by
BTW, the thread on sage-devel is http://groups.google.com/group/sage-devel/browse_thread/thread/b809aff6e97085b9
comment:3 Changed 9 years ago by
- Cc kcrisman added
comment:4 Changed 8 years ago by
- Reviewers set to Volker Braun
- Status changed from new to needs_review
This is superseded by #13109.
comment:5 Changed 8 years ago by
- Status changed from needs_review to positive_review
comment:6 Changed 8 years ago by
- Milestone changed from sage-5.1 to sage-duplicate/invalid/wontfix
comment:7 Changed 8 years ago by
- Resolution set to duplicate
- Status changed from positive_review to closed
On sage-devel, Florent Hivert recommends looking at tickets #7515, #7559, and #8073 for information related to this ticket.