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. 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 -~----------~----~----~----~------~----~------~--~---
