On Jan 24, 2008 8:12 AM, Jason Grout <[EMAIL PROTECTED]> wrote:
>
>
> William Stein wrote:
> > On Jan 24, 2008 7:14 AM, Jason Grout <[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
-~----------~----~----~----~------~----~------~--~---

Reply via email to