I think the best way to handle deprecation is to throw an error when the (now invalid) command/options are being used. This way any users of the code will know exactly what the problem is, no matter if they wrote it or how deep it is. After a period of time, this error code can be removed.
Of course, good documentation is valuable to have too, and not all errors make valid code invalid. - Robert On Jan 24, 2008, at 8:34 AM, William Stein wrote: > On Jan 24, 2008 8:12 AM, Jason Grout <[EMAIL PROTECTED]> > wrote: >> >> >> William Stein wrote: >>> On Jan 24, 2008 7:14 AM, Jason Grout <jason- >>> [EMAIL PROTECTED]> wrote: >>>> The discussion related to #1900 brings up a point about backwards >>>> compatibility. Last summer, it seemed like we could change the >>>> interface from version to version and it wasn't a big deal---the >>>> community was small enough and updated often enough that we weren't >>>> worried about preserving or even really documenting backward >>>> incompatible changes. However, with the recent surge in users and >>>> interest, maybe it's time that we at least document changes >>>> which are >>>> not compatible with previous releases, even if we don't have a >>>> "deprecated function" functionality just yet. >>>> >>>> What does everyone think? I'm imagining just a short changelog- >>>> style >>>> file in the root directory and/or the documentation that would >>>> document >>>> changes to functions which would affect people upgrading from >>>> previous >>>> releases. For example, in #1900 the issue is whether to remove a >>>> parameter from the adjacency_matrix function. If someone is >>>> using that >>>> parameter, then their code will blow up when they upgrade (if >>>> the patch >>>> is applied). A short note in a file like the following could help >>>> tremendously: >>>> >>>> * (Di)Graph.adjacency_matrix() and (Di)Graph.am() no longer >>>> accept the >>>> over_integers parameter and a matrix over the integers is >>>> returned in >>>> each case now. If G is a (di)graph with G.multiple_edges() >>>> ==False, then >>>> G.adjacency_matrix(over_integers=True) --> G.adjacency_matrix() and >>>> G.adjacency_matrix(over_integers=False) or G.adjacency_matrix() --> >>>> matrix(GF(2),G). >>>> >>>> It may be better if there were a way to do a short table with >>>> columns >>>> "Old functionality" and "Equivalent new functionality" or a short >>>> documentation paragraph like the following: >>>> >>>> If G is a (di)graph where G.multiple_edges()==False, then >>>> >>>> before 2.10.1: G.adjacency_matrix() or >>>> G.adjacency_matrix(over_integers=False) >>>> >>>> is equivalent to >>>> >>>> 2.10.1: matrix(GF(2),G) >>>> >>>> and >>>> >>>> before 2.10.1: G.adjacency_matrix(over_integers=True) >>>> >>>> is equivalent to >>>> >>>> 2.10.1: G.adjacency_matrix() >>>> >>>> >>>> I think documenting these sorts of changes will help users not be >>>> frustrated with a new release every week in which their code >>>> might break :). >>> >>> +1 >>> >>> The easiest way to implement this *might* be to come up with >>> a very simple format, then just recall that the changelog for >>> committing >>> code that changes the Sage interface document that change. Then >>> the list you describe above could be automatically extracted at any >>> time between any two versions of Sage. >> >> I think necessary fields are: >> >> * Version in which the change happened > > If we make this part of the hg commit messages, then this is not > needed, > since hg will know the version. > >> >> * the function or class in which the change is apparent > > This is likely implicit in the old to new syntax table you propose > below. > >> >> * a short text field describing the change and possibly a very short >> rational for the change (with maybe a link to the discussion that of >> course happened on sage-devel and the trac ticket (or IRC if that is >> logged someplace permanent)) > > Any hg commit message should have the trac ticket number in it too. > >> >> * the text field possibly interspersed with a table, or maybe >> followed >> by a table, summarizing how to convert old syntax to new syntax >> and get >> equivalent functionality. > > This is good. > >> Any others fields? It would be nice to have some sort of formatting, >> especially formatting of code and math. > > I think it would be best if the actual format that goes in hg commit > messages is so incredibly simple that I can actually remember, since > otherwise I likely won't bother. If it means memorizing 5 fields to > fill in, there's no way it will get used. Since basically everything > listed above can be autoextracted (or easily found via search > in trac or google groups) except that the summary of > how to convert from the old format to the new one, I think that's the > thing that should be important. E.g., we could just require > something > very easy like this in the hg log whenever an interface change happens > that will break backwards compatibility: > > CHANGE: For G a a graph, G.adjacency_matrix(over_integers=True) ==> > G.adjacency_matrix() > [Optional free-form paragraph about what/why] > > CHANGE: For G a graph, G.adjacency_matrix() or > G.adjacency_matrix(over_integers=False) ==> matrix(GF(2),G) > > That's it. Usually the things on each side of ==> should just be > python code, though they > could also be English. Another example from > > http://trac.sagemath.org/sage_trac/ticket/1911 > > CHANGE: For E an elliptic curve over QQ, E.heegner_index().sqrt() ==> > E.heegner_index() > [It used to be the case that E.heegner_index() actually returned the > square of the Heegner index. This confusing behavior has now been > fixed.] > > -- William > > --~--~---------~--~----~------------~-------~--~----~ To post to this group, send email to sage-devel@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sage-devel URLs: http://www.sagemath.org -~----------~----~----~----~------~----~------~--~---
