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 ddrake

On sage-devel, Florent Hivert recommends looking at tickets #7515, #7559, and #8073 for information related to this ticket.

comment:3 Changed 9 years ago by kcrisman

  • Cc kcrisman added

comment:4 Changed 8 years ago by kcrisman

  • Reviewers set to Volker Braun
  • Status changed from new to needs_review

This is superseded by #13109.

comment:5 Changed 8 years ago by kcrisman

  • Status changed from needs_review to positive_review

comment:6 Changed 8 years ago by kcrisman

  • Milestone changed from sage-5.1 to sage-duplicate/invalid/wontfix

comment:7 Changed 8 years ago by jdemeyer

  • Resolution set to duplicate
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.