9.4 Reviewing Patches

All code that goes into Sage is peer-reviewed, to ensure that the conventions discussed in this manual are followed, to make sure that there are sufficient examples and doctests in the documentation, and to try to make sure that the code does, mathematically, what it is supposed to.

If someone (other than you) has posted a patch for a ticket on the trac server, you can review it. Look at the patch (by clicking on the file name in the list of attachments) to see if it makes sense. Download it (from the window displaying the patch, see the ``Download'' option at the bottom of the page). Apply it (using hg_sage.patch('filename'), for example) to your copy of Sage, and build Sage with the new code by typing sage -b.

Now ask yourself questions like these:

Does the new source code make sense?
When you run it in Sage, does it fix the problem reported on the ticket?
Does it fail to introduce any new problems?
Is it documented sufficiently, including both explanations and doctests? (This is very important: all code in Sage must have doctests, so even if the patch is for code which didn't have a doctest before, the new version must include one.)
In particular, is there a doctest illustrating that the bug has been fixed? If a function used to give the wrong answer and this patch fixes that, then if possible, it should include a doctest illustrating its new success.

If the answers to these and other such reasonable questions are yes, then you might want to give the patch a positive review. On the main ticket page, write a comment in the box and change the summary from [with patch, needs review] description of bug to [with patch, positive review] description of bug. If you feel there are issues with the patch, explain them in the comment box, and change the summary to [with patch, negative review] description of bug, or [with patch, needs work] description of bug, or [with patch, positive review pending fixes] description of bug, or something similar. Browse the tickets on the trac server to see how things are done.

By the way, if you review a patch which deals with the Sage manuals, say, instead of the source code, then you need to use hg_doc.patch('filename') instead of hg_sage.patch('filename') to apply it, and you need to follow the directions in Chapter 5 to build the new documentation.

See About this document... for information on suggesting changes.