On May 26, 2010, at 12:49 PM, Jason Grout wrote:
On 5/26/10 5:33 AM, William Stein wrote:
Your arguments would also suggest that any of the Sage repositories
should
have their logs in a text file as well. Should the main Sage Python
library!? Should the
local/bin/ repository have a text file?
You know, for certain things, this might not be a bad idea. For
example, we have no listing of compatibility breakages between Sage
versions, which has often tripped things up for me and others that I
know. If there was a simple changelog mentioning big changes that
might break people's code, then it would be much easier for an
enduser to know if they should upgrade, or know how to fix their
code if they did upgrade. Yes, I know there should be deprecation
warnings for every change that could break user code, but that isn't
always followed and can put a huge burden on the code in some cases
(like a re-architecturing of a subsystem, etc.). Also, deprecation
warnings don't help someone who is trying to proactively determine
if their existing code will work before upgrading.
Right now, of course, you could point to the listing given in the
release notes. However, often the trac ticket titles are (1) not
very descriptive, (2) often poorly reflect what is actually in the
patch, and (3) do not give any information about deprecations or
other user-visible changes. On the other hand, reading all of the
discussion on all of the trac tickets and then looking at all of the
patches is clearly out of the question for most users to see what
changed.
Trac ticket titles and descriptions should be updated as a ticket
evolves. Ideally
http://trac.sagemath.org/sage_trac/query?group=component&milestone=sage-4.4.2
should be a good summary of what happened.
Of course, an alternative is to just make a special section of the
commit message detailing possible compatibility issues, and then
just automatically pull those out when making a release. If we did
that, commit messages could be something like docstrings with
sections for features added, compatibility issues, other user-
visible changes, etc. Wow, that sounds like a lot of work too. But
it could make Sage much more user-friendly.
That would be cool too, actually ideal.
- Robert
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
