Sage Days 28
Orsay, France, January 17-19th 2011
Sage is distributed under the terms of the GNU General Public License version 2 (GPLv2) which provides four kinds of freedom:
While all users of Sage make use of the first freedom, in this talk, we will see how to appropriate the other three.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
That's the easiest part. Choose one amongst this
selection of unreported documentation bugs
made for Sage Days 28 or browse the
Open Beginner Tickets.
During this talk, instead of fixing a bug I am going to introduce one in the inverse method of a permutation.
In Sage, modifications are tracked on a web site called Sage trac. Every bug gets assigned a number. For instance, the number #10484 refers to the bug called Chinese remainder code raises an error when called with Python ints. On the ticket, one can see that:
One can also look at the solution, download it, test it, etc.
In order to create a ticket:
I create the imaginary ticket #12345 for introducing a useless print statement in the method that computes the inverse of a permutation.
To use Sage from any directory, you need to make your computer know about Sage. Personally, my sage installation is in ~/Applications/sage-4.6.1. So one way to do this is to add the following line to the file ~/.bashrc:
export PATH=~/Applications/sage-4.6.1:$PATH
This allows you to start sage from any directory:
slabbe@pol ~ $ sage ---------------------------------------------------------------------- | Sage Version 4.6.1, Release Date: 2011-01-20 | | Type notebook() for the GUI, and license() for information. | ---------------------------------------------------------------------- sage:
Note
You might have to open a new terminal to make this work.
This creates a new directory called sage-slabbe in the devel repository:
slabbe@pol ~/Applications/sage-4.6.1/devel $ ls -l drwxr-xr-x 2 slabbe staff 68 14 jan 03:59 old/ lrwxr-xr-x 1 slabbe staff 9 18 jan 15:01 sage -> sage-main/ drwxr-xr-x 23 slabbe staff 782 18 jan 01:42 sage-main/ drwxr-xr-x 24 slabbe staff 816 17 jan 01:50 sage-slabbe/ lrwxr-xr-x 1 slabbe staff 11 14 jan 03:42 sagenb -> sagenb-main/ drwxr-xr-x 21 slabbe staff 714 14 jan 03:41 sagenb-main/
| Build the main branch | Build my branch slabbe | Print the current branch |
| sage -b main | sage -b slabbe | sage -branch |
Sage uses the program Mercurial ( hg or sage -hg ) to manage all of its source code. Mercurial stores the evolution of every single file of Sage since the beginning.
Since I am too lazy to write sage -hg everytime I use Mercurial, I added the following line to my ~/.bashrc file:
alias hg='sage -hg'
I verify that it works:
slabbe@pol ~ $ hg --version Mercurial Distributed SCM (version 1.6.4) Copyright (C) 2005-2010 Matt Mackall <mpm@selenic.com> and others This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
slabbe@pol ~/Applications/sage-4.6.1/devel/sage-main $ hg log changeset: 15205:f24ce048fa66 tag: tip user: Jeroen Demeyer date: Tue Jan 11 08:10:26 2011 +0100 summary: 4.6.1 ... changeset: 0:039f6310c6fe user: tornaria date: Sat Feb 11 01:13:08 2006 +0000 summary: [project @ original sage-0.10.12]
Mercurial queues is an extension to Mercurial that allows one to easily work with collections of patches. To allow Mercurial queues, edit (or create) the file ~/.hgrc and make sure it contains the line hgext.mq = in the extensions section:
[ui] username = Sebastien Labbe <hidden adress email> [extensions] hgext.mq = color = [alias] qstatus = status --rev -2:.
Warning
The line hgext.mq= is an indispensable for the next steps.
cd to your branch:
cd Applications/sage-4.6.1/devel/sage-slabbe
Create a new empty patch:
hg qnew trac_12345-add_useless_print-sl.patch
Find the file containing the bug
Personnally I found the file permutation.py here:
sage-4.6.1/devel/sage-slabbe/sage/combinat/permutation.py
Find the solution to the bug
Edit the source code accordingly, save and quit
Now, you may use the following Mercurial commands to look at your local changes.
hg status shows changed files since last hg qnew (or hg qrefresh):
slabbe@pol ~/Applications/sage-4.6.1/devel/sage-combinat/sage/combinat $ hg status M sage/combinat/permutation.py
hg diff shows differences since last hg qnew (or hg qrefresh)
slabbe@pol ~/Applications/sage-4.6.1/devel/sage-combinat/sage/combinat $ hg diff
diff --git a/sage/combinat/permutation.py b/sage/combinat/permutation.py
--- a/sage/combinat/permutation.py
+++ b/sage/combinat/permutation.py
@@ -1208,6 +1208,7 @@ class Permutation_class(CombinatorialObj
sage: Permutation([2, 4, 1, 5, 3]).inverse()
[3, 1, 5, 2, 4]
"""
+ print "YO !!!! Let's inverse some permutations !!!"
w = range(len(self))
for i,j in enumerate(self):
w[j-1] = i+1
sage: p = Permutation([4,3,2,5,1]) sage: p.inverse() YO !!!! Let's inverse some permutations !!! [5, 3, 2, 1, 4]
That's great: we are now able to modify Sage.
slabbe@pol ~/Applications/sage-4.6.1/devel/sage-slabbe/sage/combinat $ sage -t permutation.py
sage -t "devel/sage-slabbe/sage/combinat/permutation.py"
**********************************************************************
File "/Users/slabbe/Applications/sage-4.6.1/devel/sage-slabbe/sage/combinat/permutation.py", line 1206:
sage: Permutation([3,8,5,10,9,4,6,1,7,2]).inverse()
Expected:
[8, 10, 1, 6, 3, 7, 9, 2, 5, 4]
Got:
YO !!!! Let's inverse some permutations !!!
[8, 10, 1, 6, 3, 7, 9, 2, 5, 4]
----------------------------------------------------------------------
The following tests failed:
sage -t "devel/sage-slabbe/sage/combinat/permutation.py"
Total time for all tests: 10.4 seconds
If tests failed, one should edit files again...
Build the documentation and make sure there are no errors or warnings:
sage -b && sage -docbuild reference html
Open the html version of documentation in your browser and make sure the documentation looks OK:
open ~/Applications/sage-4.6.1/devel/sage/doc/output/html/en/reference/sage/combinat/permutation.html
When the bug is fixed, once we made sure every tests pass and that the documentation builds fine, then we can update the current patch with hg qrefresh to reflect the changes:
hg qrefresh
No changes are shown anymore by hg status or hg diff:
hg status hg diff
Modifications are now in the patch. See hg qstatus or hg qdiff:
hg qstatus hg qdiff
Add a commit message to the patch:
hg qrefresh -m "#12345: add a useless print in the inverse method of a permutation"
Export the patch with hg export:
hg export trac_12345-add_useless_print-sl.patch >
~/Documents/tmp/trac_12345-add_useless_print-sl.patch
The command hg export also adds informations in the patch (author name, date, ...).
Note
Personnaly, I added the following alias to my ~/.bashrc:
alias qtoptotmp='hg export `hg qtop` > ~/Documents/tmp/`hg qtop`'
Here is an example of a patch exported by Mercurial for the imaginary ticket #12345. It contains information about the author, the date, the commit message we just wrote and finally the complete diff.
trac_12345-add_useless_print-sl.patch:
# HG changeset patch
# User Sebastien Labbe <hidden adress email>
# Date 1295311529 -3600
# Node ID 4a6379cf0c965e1ce309846cbcb9f864932a3b6c
# Parent 83e5e45a8935ac627c45ed14042bbebafeb1a800
#12345: add a useless print in the inverse method of a permutation
diff --git a/sage/combinat/permutation.py b/sage/combinat/permutation.py
--- a/sage/combinat/permutation.py
+++ b/sage/combinat/permutation.py
@@ -1208,6 +1208,7 @@ class Permutation_class(CombinatorialObj
sage: Permutation([2, 4, 1, 5, 3]).inverse()
[3, 1, 5, 2, 4]
"""
+ print "YO !!!! Let's inverse some permutations !!!"
w = range(len(self))
for i,j in enumerate(self):
w[j-1] = i+1
Upload the patch on Sage trac
You can mention things like "tested on sage-4.6.1" in the text box when uploading the ticket.
Make sure the patch was correctly uploaded by looking at it directly on the web page.
Set the ticket to needs review
You may ask somebody to review your ticket.
Other useful Mercurial commands when patches multiplies:
A feature available on a Sage Trac ticket interests you? You want to review a ticket?
Download a patch!
Insert a patch into the series after the last applied patch with hg qimport:
hg qimport ~/Downloads/trac_65321-nice-feature-AA.patch
Warning
Do NOT use the command hg import as it will import the changes in the current patch.
You can change the order in which the patches are applied. To do so, simply edit the series file:
slabbe@pol ~/Applications/sage-4.6.1/devel/sage-slabbe $ cd .hg/patches/ slabbe@pol ~/Applications/sage-4.6.1/devel/sage-slabbe/.hg/patches $ vim series
Make sure the patch you are reviewing is the first patch to be applied:
slabbe@pol ~/Applications/sage-4.6.1/devel/sage-slabbe/.hg/patches $ cat series trac_65321-nice-feature-AA.patch A.patch B.patch C.patch
Warning
Visit the Reviewing a patch Section of the Sage Developer's Guide. Also, make sure you read William Stein's blog post about reviewing a Sage trac ticket.
Experiment the functionality proposed in the patch.
Once you’ve tested the patch, report any failures on the Trac page for the ticket. Make suggestions about simplifying the code or fixing typos you noticed.
Three cases may happen:
Note
Delete an (unapplied) patch from the queue:
hg qdelete trac_65321-nice-feature-AA.patch
Erase your branch. Of course, do this only if you don't care about your local changes:
rm -rf sage-slabbe
Reviewing a Sage trac ticket, William Stein's blog post, October 31, 2010.
This talk was generated