#13109: Rewrite deprecation to use trac ticket numbers
--------------------------------+-------------------------------------------
Reporter: vbraun | Owner: mvngu
Type: enhancement | Status: needs_review
Priority: major | Milestone: sage-5.1
Component: doctest | Resolution:
Keywords: | Work issues:
Report Upstream: N/A | Reviewers: John Palmieri, Karl-Dieter
Crisman
Authors: Volker Braun | Merged in:
Dependencies: #12544 | Stopgaps:
--------------------------------+-------------------------------------------
Changes (by jhpalmieri):
* reviewer: => John Palmieri, Karl-Dieter Crisman
Old description:
> As discussed on https://groups.google.com/d/topic/sage-
> devel/I12IeaFlE7g/discussion, change the deprecation function to the new
> arguments
> {{{
> deprecation(trac_number, message)
> }}}
> where both arguments are mandatory. Once this code is in Sage, one
> can deduce every possible thing discussed above in this thread from
> the trac number. The deprecation warning can produce the URL of the
> trac ticket.
>
> Analogous changes are made to `deprecated_function_alias` and
> `deprecated_callable_import`. Finally, the
> `@rename_keyword(deprecated="sage version string", ...)` decorator is
> changed to
> {{{
> @rename_keyword(deprecation=<trac_number>, ...)
> }}}
>
> Apply
> * [attachment:trac_13109_deprecation.patch]
> * [attachment:trac_13109_ticket_numbers.patch]
> * [attachment:trac_13109_fix_doctests.patch]
> * [attachment:trac_13109_documentation.patch]
>
> This ticket also fixes #8073, #8546.
New description:
As discussed on https://groups.google.com/d/topic/sage-
devel/I12IeaFlE7g/discussion, change the deprecation function to the new
arguments
{{{
deprecation(trac_number, message)
}}}
where both arguments are mandatory. Once this code is in Sage, one
can deduce every possible thing discussed above in this thread from
the trac number. The deprecation warning can produce the URL of the
trac ticket.
Analogous changes are made to `deprecated_function_alias` and
`deprecated_callable_import`. Finally, the
`@rename_keyword(deprecated="sage version string", ...)` decorator is
changed to
{{{
@rename_keyword(deprecation=<trac_number>, ...)
}}}
Apply
* [attachment:trac_13109_deprecation.patch]
* [attachment:trac_13109_ticket_numbers.patch]
* [attachment:trac_13109_fix_doctests.patch]
* [attachment:trac_13109_documentation.v2.patch]
This ticket also fixes #8073, #8546.
--
Comment:
Regarding the documentation: it looks great, but I have three suggestions:
first, change "user's" to "users'" in line 4 of the first paragraph.
Second, make it a section instead of a subsection so it shows up in the
main table of contents for the developer's guide (change the hyphens
`-----` to equals signs `======`). Third, move it to the chapter on
"coding in python": right now it's in the middle of the doctesting stuff,
and the Python chapter contains information relevant to both Python and
Cython (despite the chapter title -- maybe the chapter should be "Coding
in Python and Cython" and the following one should be "Issues specific to
coding in Cython", but anyway...). I'm attaching a version of the patch
making these changes.
For the "ticket numbers" and "fix doctests" patches, I've done a bit of
spot-checking, and it all looks good. The "deprecation" patch basically
moves the deprecation code from misc.py to superseded.py, with some small
modifications, right? That looks good, too. Is there any reason to do any
error-checking on the trac number argument? Right now, using
{{{
#!python
def foo():
sage.misc.superseded.deprecation('blah', 'the function foo is
deprecated.')
}}}
works without error. (I'm fine with the current state of affairs, I'm just
asking the question.)
Anyway, positive review for everything except for my version of the
documentation.
--
Ticket URL: <http://trac.sagemath.org/sage_trac/ticket/13109#comment:22>
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.
