deprecation dates?

[John Cremona]

We have a rule about giving a deprecation output warning when the user
interface of a function changes, and somewhere is written down how
long that should remain in place. But is there an easy way to tell?

I tried using "hg blame" which tagged the lines I was looking at with
the number 12039, but that does not refer to a relevant trac ticket.
I put the number into the search box at
http://hg.sagemath.org/sage-main and miraculously the first hit led me
to changeset 12039:b9efad4a61dd, dated Fri Apr 03 16:29:44 2009 -0700
(3 years ago) -- which is not the right one, looks like a reviewer's
patch -- and the second hit seems to be the one I was looking for
(same date).

Perhaps it would make life simpler if whenever people write code
introducing a new deprecation warning, there's a date? Though the
time of writing the code and the date of the release can be years
apart, so what then?

In the case I was looking at (for ticket #13100) I think I am sage in
removing the deprecation messages, and my patch there will do so.

John

[Volker Braun]

The deprecation warning should include the Sage version where it was deprecated, as in

deprecation('foobar is deprecated', 'Sage Version 4.8')

[John Cremona]

On 10 June 2012 17:29, Volker Braun <vbrau...@gmail.com> wrote:
> The deprecation warning should include the Sage version where it was
> deprecated, as in
>
> deprecation('foobar is deprecated', 'Sage Version 4.8')
>

Sounds good. I looked for something about deprecation warnings in the
developers' guide but found nothing. Where is it?

John

>
>
> On Sunday, June 10, 2012 5:23:36 PM UTC+1, John Cremona wrote:
>>
>> We have a rule about giving a deprecation output warning when the user
>> interface of a function changes, and somewhere is written down how
>> long that should remain in place.  But is there an easy way to tell?
>>
>> I tried using "hg blame" which tagged the lines I was looking at with
>> the number 12039, but that does not refer to a relevant trac ticket.
>> I put the number into the search box at
>> http://hg.sagemath.org/sage-main and miraculously the first hit led me
>> to changeset 12039:b9efad4a61dd, dated Fri Apr 03 16:29:44 2009 -0700
>> (3 years ago) -- which is not the right one, looks like a reviewer's
>> patch -- and the second hit seems to be the one I was looking for
>> (same date).
>>
>> Perhaps it would make life simpler if whenever people write code
>> introducing a new deprecation warning, there's a date?  Though the
>> time of writing the code and the date of the release can be years
>> apart, so what then?
>>
>> In the case I was looking at (for ticket #13100) I think I am sage in
>> removing the deprecation messages, and my patch there will do so.
>>
>> John
>

> --
> To post to this group, send an email to sage-...@googlegroups.com
> To unsubscribe from this group, send an email to
> sage-devel+...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/sage-devel
> URL: http://www.sagemath.org

[Volker Braun]

The lack of documentation for deprecation in the developer guide is http://trac.sagemath.org/sage_trac/ticket/8546

[Keshav Kini]

Volker Braun <vbrau...@gmail.com> writes:
> The deprecation warning should include the Sage version where it was
> deprecated, as in
>
> deprecation('foobar is deprecated', 'Sage Version 4.8')

This means that the author of a patch needs to be able to know which
version of Sage their patch will go into, i.e. if the release manager
bumps the milestone on a ticket which introduces a deprecation warning,
he should also change it back to needs_work. Yes?

-Keshav

----
Join us in #sagemath on irc.freenode.net !

[John Cremona]

On 10 June 2012 20:42, Keshav Kini <kesha...@gmail.com> wrote:
> Volker Braun <vbrau...@gmail.com> writes:
>> The deprecation warning should include the Sage version where it was
>> deprecated, as in
>>
>> deprecation('foobar is deprecated', 'Sage Version 4.8')
>
> This means that the author of a patch needs to be able to know which
> version of Sage their patch will go into, i.e. if the release manager
> bumps the milestone on a ticket which introduces a deprecation warning,
> he should also change it back to needs_work. Yes?

This does not sound reasonable to me: when lots of release numbers are
bumped up one cannot expect a release manager to look at every patch
to see if some new deprecation warning is in there.

John

>
> -Keshav
>
> ----
> Join us in #sagemath on irc.freenode.net !
>

[Keshav Kini]

John Cremona <john.c...@gmail.com> writes:
> On 10 June 2012 20:42, Keshav Kini <kesha...@gmail.com> wrote:
>> Volker Braun <vbrau...@gmail.com> writes:
>>> The deprecation warning should include the Sage version where it was
>>> deprecated, as in
>>>
>>> deprecation('foobar is deprecated', 'Sage Version 4.8')
>>
>> This means that the author of a patch needs to be able to know which
>> version of Sage their patch will go into, i.e. if the release manager
>> bumps the milestone on a ticket which introduces a deprecation warning,
>> he should also change it back to needs_work. Yes?
>
> This does not sound reasonable to me: when lots of release numbers are
> bumped up one cannot expect a release manager to look at every patch
> to see if some new deprecation warning is in there.

Right, that's what I was thinking too.

On the other hand, putting the date in the patch isn't correct either
since the patch may sit around needing review for months or years.

[Volker Braun]

Instead of designing a process to ensure that the deprecation version is absolutely correct we should spend some effort to timely review tickets :-P

[Keshav Kini]

Volker Braun <vbrau...@gmail.com> writes:

> Instead of designing a process to ensure that the deprecation version is
> absolutely correct we should spend some effort to timely review tickets :-P

While that is an admirable goal, maybe the best way to handle this is to
create a wiki page listing deprecations and what release of Sage they
were introduced in, as I suggested on sage-devel many months ago [1], as
I recall :P I would have done it myself but apparently I forgot about
it...

[1] http://thread.gmane.org/gmane.comp.mathematics.sage.devel/53717

[Volker Braun]

Keeping the deprecation wiki, trac, and the Sage library in sync seems hopeless. How about we 

a) add the ticket where it was introduced as an argument to the deprecation(msg, sage_version, trac_number) 

b) document this in the developer manual

[William Stein]

On Sun, Jun 10, 2012 at 4:31 PM, Volker Braun <vbrau...@gmail.com> wrote:
> Keeping the deprecation wiki, trac, and the Sage library in sync seems
> hopeless. How about we
>
> a) add the ticket where it was introduced as an argument to the
> deprecation(msg, sage_version, trac_number)
> b) document this in the developer manual

+1 -- that's a viable proposal.

>
>
>
> On Sunday, June 10, 2012 10:40:36 PM UTC+1, Keshav Kini wrote:
>>
>> Volker Braun <vbrau...@gmail.com> writes:
>>
>> > Instead of designing a process to ensure that the deprecation version is
>> > absolutely correct we should spend some effort to timely review tickets
>> > :-P
>>
>> While that is an admirable goal, maybe the best way to handle this is to
>> create a wiki page listing deprecations and what release of Sage they
>> were introduced in, as I suggested on sage-devel many months ago [1], as
>> I recall :P I would have done it myself but apparently I forgot about
>> it...
>>
>> [1] http://thread.gmane.org/gmane.comp.mathematics.sage.devel/53717
>>
>> -Keshav
>>
>> ----
>> Join us in #sagemath on irc.freenode.net !
>>

> --
> To post to this group, send an email to sage-...@googlegroups.com
> To unsubscribe from this group, send an email to
> sage-devel+...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/sage-devel
> URL: http://www.sagemath.org

--
William Stein
Professor of Mathematics
University of Washington
http://wstein.org

[Keshav Kini]

Volker Braun <vbrau...@gmail.com> writes:

> Keeping the deprecation wiki, trac, and the Sage library in sync seems
> hopeless.

Why? I disagree. Each deprecation warning is introduced into a Sage
release once, and removed from Sage in a release once. Each time the
former happens, you needs to add it to the wiki - if you forget, you can
do it later using `hg blame`. Each time the latter happens, you just
delete it from the wiki - if you forget, you can do it later by noticing
that the deprecation warning isn't there anymore.

What's hopeless about that?

[John Cremona]

On 11 June 2012 03:38, William Stein <wst...@gmail.com> wrote:
> On Sun, Jun 10, 2012 at 4:31 PM, Volker Braun <vbrau...@gmail.com> wrote:
>> Keeping the deprecation wiki, trac, and the Sage library in sync seems
>> hopeless. How about we
>>
>> a) add the ticket where it was introduced as an argument to the
>> deprecation(msg, sage_version, trac_number)
>> b) document this in the developer manual
>
> +1  -- that's a viable proposal.
>

+1

I guess the new trac_number field will have to default to None, unless
we want to raise a deprecation warning whenever deprecation() is only
called with two arguments...infiinte loop?!

I count about 132 times where deprecation is imported and about 70
times where deprecation() is called. Roughly.

John

[Volker Braun]

Maybe I'm the hopeless case, but manually updating the wiki to be in sync isn't what I like to spend my time on :-)

[William Stein]

On Mon, Jun 11, 2012 at 1:54 AM, John Cremona <john.c...@gmail.com> wrote:
> On 11 June 2012 03:38, William Stein <wst...@gmail.com> wrote:
>> On Sun, Jun 10, 2012 at 4:31 PM, Volker Braun <vbrau...@gmail.com> wrote:
>>> Keeping the deprecation wiki, trac, and the Sage library in sync seems
>>> hopeless. How about we
>>>
>>> a) add the ticket where it was introduced as an argument to the
>>> deprecation(msg, sage_version, trac_number)
>>> b) document this in the developer manual
>>
>> +1  -- that's a viable proposal.
>>
>
> +1
>
> I guess the new trac_number field will have to default to None, unless
> we want to raise a deprecation warning whenever deprecation() is only
> called with two arguments...infiinte loop?!
>
> I count about 132 times where deprecation is imported and about 70
> times where deprecation() is called.  Roughly.

I would just suggest:

deprecation(msg,trac_number)

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. In my opinion this (Volker's suggestion) is a brilliant
solution to this problem.

William

-- William

[Jason Grout]

On 6/11/12 10:02 AM, William Stein wrote:

> I would just suggest:
>
> deprecation(msg,trac_number)
>
> 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. In my opinion this (Volker's suggestion) is a brilliant
> solution to this problem.

+1. In fact, since the trac number is automatically included in the
commit message, you don't even need to access trac to determine which
sage version number the ticket was merged in.

Jason

[Jason Grout]

On 6/11/12 10:02 AM, William Stein wrote:

>> I guess the new trac_number field will have to default to None, unless
>> we want to raise a deprecation warning whenever deprecation() is only
>> called with two arguments...infiinte loop?!
>>
>> I count about 132 times where deprecation is imported and about 70
>> times where deprecation() is called. Roughly.
>
> I would just suggest:
>
> deprecation(msg,trac_number)
>
> 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. In my opinion this (Volker's suggestion) is a brilliant
> solution to this problem.

It would also be great if there was an automatic way to generate a
"Deprecated" section of the release notes so people don't have to
actually bump into the wall to realize something is deprecated.

Jason

[Volker Braun]

I've started to work on this at http://trac.sagemath.org/sage_trac/ticket/13109. In fact, I'll do

deprecation(trac_number, msg) 

In particular this makes it clear that trac_number is not optional.