How to contribute to Sage -- Thematic Tutorials v4.7.rc0
system:sage


<div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index" accesskey="I">index</a></li>
  
    
      <a href="../index.html"><img src="_static/sagelogo.png" style="vertical-align: middle" title="Sage Logo"></a>
    
  
  
        <li><a href="index.html">Thematic Tutorials v4.7.rc0</a> &raquo;</li>
 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="how-to-contribute-to-sage">
<span id="demo-how-to-contribute"></span><h1>How to contribute to Sage<a class="headerlink" href="#how-to-contribute-to-sage" title="Permalink to this headline">¶</a></h1>
<div class="section" id="s-bastien-labb">
<h2>Sébastien Labbé<a class="headerlink" href="#s-bastien-labb" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="center">
<em class="property">class </em><tt class="descname">center</tt><a class="headerlink" href="#center" title="Permalink to this definition">¶</a></dt>
<dd><div class="line-block">
<div class="line"><em>If the slide text doesn&#8217;t fit in your browser window, try decreasing the text size.</em></div>
<div class="line"><em>Type</em> <tt class="docutils literal"><span class="pre">T</span></tt> <em>if you have trouble viewing this presentation.</em></div>
</div>
<p><strong>Sage Days 28</strong></p>
<p>Orsay, France, January 17-19th 2011</p>
</dd></dl>

<div class="section" id="gnu-general-public-licence">
<h3>GNU General Public Licence<a class="headerlink" href="#gnu-general-public-licence" title="Permalink to this headline">¶</a></h3>
<p>Sage is distributed under the terms of the GNU General Public License version 2
(<a class="reference external" href="http://www.gnu.org/licenses/">GPLv2</a>) which provides four kinds of freedom:</p>
<ul class="simple">
<li>Freedom to <span class="red">run the program</span></li>
<li>Freedom to <span class="red">access the code</span></li>
<li>Freedom to <span class="red">redistribute the program to anyone</span></li>
<li>Freedom to <span class="red">improve the software</span></li>
</ul>
<p>While all users of Sage make use of the first freedom, in this talk, we will see
<span class="red">how to appropriate the other three</span>.</p>
</div>
<div class="section" id="twenty-two-easy-steps">
<h3>Twenty Two Easy Steps<a class="headerlink" href="#twenty-two-easy-steps" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="borderless">
<em class="property">class </em><tt class="descname">borderless</tt><a class="headerlink" href="#borderless" title="Permalink to this definition">¶</a></dt>
<dd><table border="1" class="docutils">
<colgroup>
<col width="50%">
<col width="50%">
</colgroup>
<tbody valign="top">
<tr><td><ol class="first last arabic simple">
<li>Find a bug</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="12">
<li>Build the documentation</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="2">
<li>Sage trac server</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="13">
<li>Update the current patch</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="3">
<li>Create a ticket</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="14">
<li>Export a patch</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="4">
<li>Clone your Sage</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="15">
<li>Verify the patch</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="5">
<li>Mercurial</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="16">
<li>Upload the patch</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="6">
<li>Enable Mercurial queues</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="17">
<li>More on Mercurial queues</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="7">
<li>Create an empty patch</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="18">
<li>Dowload a patch</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="8">
<li>Fix the bug</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="19">
<li>Edit the series file</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="9">
<li>View your changes</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="20">
<li>Reviewing a patch</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="10">
<li>Test the changes</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="21">
<li>Positive review or Needs work</li>
</ol>
</td>
</tr>
<tr><td><ol class="first last arabic simple" start="11">
<li>Run tests</li>
</ol>
</td>
<td><ol class="first last arabic simple" start="22">
<li>Do some cleaning</li>
</ol>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<div class="incremental center container">
<span class="huge">Are you ready?</span></div>
</div>
<div class="section" id="find-a-bug">
<h3>1. Find a bug<a class="headerlink" href="#find-a-bug" title="Permalink to this headline">¶</a></h3>
<p>That&#8217;s the easiest part. Choose one amongst this</p>
<blockquote>
<a class="reference external" href="http://wiki.sagemath.org/days28-bugs_to_report">selection of unreported documentation bugs</a></blockquote>
<p>made for Sage Days 28 or browse the</p>
<blockquote>
<a class="reference external" href="http://trac.sagemath.org/sage_trac/query?status=needs_info&status=needs_review&status=needs_work&status=new&order=priority&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&keywords=~beginner&report=38">Open Beginner Tickets</a>.</blockquote>
<p><em>During this talk, instead of fixing a bug I am going to introduce one in the
inverse method of a permutation.</em></p>
</div>
<div class="section" id="sage-trac-server">
<h3>2. Sage trac server<a class="headerlink" href="#sage-trac-server" title="Permalink to this headline">¶</a></h3>
<p>In Sage, modifications are tracked on a web site called <a class="reference external" href="http://trac.sagemath.org">Sage trac</a>. Every bug gets assigned a number. For instance,
the number <a class="reference external" href="http://trac.sagemath.org/sage_trac/ticket/10484">#10484</a> refers
to the bug called <span class="fuchsia">Chinese remainder code raises an error when called
with Python ints</span>. On the ticket, one can see that:</p>
<ul class="simple">
<li>The bug was reported and solved by <strong>David Loeffler</strong> (UK) in December 2010.</li>
<li>The ticket was positively reviewed by <strong>Robert Bradshaw</strong> (USA) and <strong>Mike Hansen</strong>.</li>
<li>The solution was merged in <tt class="docutils literal"><span class="pre">sage-4.6.2</span></tt> by <strong>Jeroen Demeyer</strong> (Belgium) on January 11th 2011.</li>
</ul>
<p>One can also look at the <span class="red">solution</span>, <span class="red">download it</span>, <span class="red">test it</span>, etc.</p>
</div>
<div class="section" id="create-a-ticket">
<h3>3. Create a ticket<a class="headerlink" href="#create-a-ticket" title="Permalink to this headline">¶</a></h3>
<p>In order to create a ticket:</p>
<ul class="simple">
<li>Create an account on <a class="reference external" href="http://trac.sagemath.org/sage_trac/register">http://trac.sagemath.org/sage_trac/register</a></li>
<li>Login to your account</li>
<li>Make sure the ticket <span class="red">does not already exists</span>.</li>
<li>Create ticket</li>
<li>In the description field, explain how should someone else understand and/or
reproduce the bug.</li>
</ul>
<p><em>I create the imaginary ticket #12345 for introducing a useless</em> <tt class="docutils literal"><span class="pre">print</span></tt>
<em>statement in the method that computes the inverse of a permutation.</em></p>
</div>
<div class="section" id="clone-your-version-of-sage">
<h3>4. Clone your version of Sage<a class="headerlink" href="#clone-your-version-of-sage" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><strong>Clone Sage and create your branch</strong> (<span class="red">Do it right now because it might take some time</span>)</dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-clone</span> <span class="pre">slabbe</span></tt></dd>
</dl>
<p>This creates a <span class="red">new directory</span> called <tt class="docutils literal"><span class="pre">sage-slabbe</span></tt> in the <tt class="docutils literal"><span class="pre">devel</span></tt> repository:</p>
<div class="tiny maroon container">
<div class="highlight-python"><pre>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 -&gt; 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 -&gt; sagenb-main/
drwxr-xr-x 21 slabbe staff 714 14 jan 03:41 sagenb-main/</pre>
</div>
</div>
<dl class="class">
<dt>
<em class="property">class </em><tt class="descname">borderless</tt></dt>
<dd></dd></dl>

<table border="1" class="docutils">
<colgroup>
<col width="33%">
<col width="33%">
<col width="33%">
</colgroup>
<tbody valign="top">
<tr><td><strong>Build the main branch</strong></td>
<td><strong>Build my branch slabbe</strong></td>
<td><strong>Print the current branch</strong></td>
</tr>
<tr><td><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-b</span> <span class="pre">main</span></tt></td>
<td><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-b</span> <span class="pre">slabbe</span></tt></td>
<td><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-branch</span></tt></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="mercurial">
<h3>5. Mercurial<a class="headerlink" href="#mercurial" title="Permalink to this headline">¶</a></h3>
<p>Sage uses the program <span class="red">Mercurial</span> ( <strong>hg</strong> or <strong>sage -hg</strong> ) to manage all
of its source code. Mercurial stores the evolution of every single file of Sage
<em>since the beginning</em>.</p>
<p>Since I am too lazy to write <strong>sage -hg</strong> everytime I use Mercurial, I added
the following line to my <tt class="docutils literal"><span class="pre">~/.bashrc</span></tt> file:</p>
<div class="red container">
<div class="highlight-python"><pre>alias hg='sage -hg'</pre>
</div>
</div>
<p>I verify that it works:</p>
<div class="tiny maroon container">
<div class="highlight-python"><pre>slabbe@pol ~ $ hg --version
Mercurial Distributed SCM (version 1.6.4)

Copyright (C) 2005-2010 Matt Mackall &lt;mpm@selenic.com&gt; 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.</pre>
</div>
</div>
</div>
<div class="section" id="id2">
<h3>5. Mercurial<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><strong>hg log</strong></dt>
<dd>Print the revision history of the specified files or the entire project.</dd>
</dl>
<div class="tiny maroon container">
<div class="highlight-python"><pre>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]</pre>
</div>
</div>
<dl class="docutils">
<dt><strong>hg update</strong></dt>
<dd>Update the repository&#8217;s working directory to the specified changeset.</dd>
</dl>
</div>
<div class="section" id="enable-mercurial-queues">
<h3>6. Enable Mercurial queues<a class="headerlink" href="#enable-mercurial-queues" title="Permalink to this headline">¶</a></h3>
<p><strong>Mercurial queues</strong> is an extension to Mercurial that allows one to easily
work with collections of patches. To allow Mercurial queues, edit (or create)
the file <tt class="docutils literal"><span class="pre">~/.hgrc</span></tt> and make sure it contains the line <span class="red">hgext.mq =</span> in
the extensions section:</p>
<div class="highlight-python"><pre>[ui]
username = Sebastien Labbe &lt;hidden adress email&gt;
[extensions]
hgext.mq =
color =
[alias]
qstatus = status --rev -2:.</pre>
</div>
<div class="small container">
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The line <tt class="docutils literal"><span class="pre">hgext.mq=</span></tt> is an indispensable for the next steps.</p>
</div>
</div>
</div>
<div class="section" id="create-an-empty-patch">
<h3>7. Create an empty patch<a class="headerlink" href="#create-an-empty-patch" title="Permalink to this headline">¶</a></h3>
<p><strong>cd to your branch</strong>:</p>
<div class="highlight-python"><pre>cd Applications/sage-4.6.1/devel/sage-slabbe</pre>
</div>
<p><strong>Create a new empty patch</strong>:</p>
<div class="highlight-python"><pre>hg qnew trac_12345-add_useless_print-sl.patch</pre>
</div>
</div>
<div class="section" id="fix-the-bug">
<h3>8. Fix the bug<a class="headerlink" href="#fix-the-bug" title="Permalink to this headline">¶</a></h3>
<p><strong>Find the file containing the bug</strong></p>
<p><em>Personnally I found the file</em> <tt class="docutils literal"><span class="pre">permutation.py</span></tt> <em>here</em>:</p>
<div class="highlight-python"><pre>sage-4.6.1/devel/sage-slabbe/sage/combinat/permutation.py</pre>
</div>
<p><strong>Find the solution to the bug</strong></p>
<p><strong>Edit the source code accordingly, save and quit</strong></p>
</div>
<div class="section" id="view-your-changes">
<h3>9. View your changes<a class="headerlink" href="#view-your-changes" title="Permalink to this headline">¶</a></h3>
<p>Now, you may use the following Mercurial commands to look at your local changes.</p>
<p><strong>hg status</strong> shows changed files since last <strong>hg qnew</strong> (or <strong>hg qrefresh</strong>):</p>
<div class="tiny maroon container">
<div class="highlight-python"><pre>slabbe@pol ~/Applications/sage-4.6.1/devel/sage-combinat/sage/combinat $ hg status
M sage/combinat/permutation.py</pre>
</div>
</div>
<p><strong>hg diff</strong> shows differences since last <strong>hg qnew</strong> (or <strong>hg qrefresh</strong>)</p>
<div class="tiny maroon container">
<div class="highlight-python"><pre>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</pre>
</div>
</div>
</div>
<div class="section" id="test-the-changes">
<h3>10. Test the changes<a class="headerlink" href="#test-the-changes" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><strong>Build sage</strong></dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-b</span></tt></dd>
<dt><strong>Verify the effects of the modification</strong></dt>
<dd>Run <tt class="docutils literal"><span class="pre">sage</span></tt></dd>
</dl>
<div class="tiny maroon container">
<div class="highlight-python">

{{{id=0|
p = Permutation([4,3,2,5,1])
p.inverse()
///
YO !!!! Let's inverse some permutations !!!
[5, 3, 2, 1, 4]
}}}

</div>
</div>
<p>That&#8217;s great: we are now able to <span class="red">modify</span> Sage.</p>
</div>
<div class="section" id="run-tests">
<h3>11. Run tests<a class="headerlink" href="#run-tests" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt><strong>Make sure that all examples in the source code still work</strong></dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-t</span> <span class="pre">&lt;files&gt;</span></tt></dd>
</dl>
<div class="tiny maroon container">
<div class="highlight-python"><pre>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</pre>
</div>
</div>
<p>If <span class="red">tests failed</span>, one should edit files again...</p>
</div>
<div class="section" id="build-the-documentation">
<h3>12. Build the documentation<a class="headerlink" href="#build-the-documentation" title="Permalink to this headline">¶</a></h3>
<p><strong>Build the documentation and make sure there are no errors or warnings</strong>:</p>
<div class="highlight-python"><pre>sage -b &amp;&amp; sage -docbuild reference html</pre>
</div>
<p><strong>Open the html version of documentation in your browser and make sure the
documentation looks OK</strong>:</p>
<div class="highlight-python"><pre>open ~/Applications/sage-4.6.1/devel/sage/doc/output/html/en/reference/sage/combinat/permutation.html</pre>
</div>
</div>
<div class="section" id="update-the-current-patch">
<h3>13. Update the current patch<a class="headerlink" href="#update-the-current-patch" title="Permalink to this headline">¶</a></h3>
<p>When the bug is fixed, once we made sure every tests pass and that the
documentation builds fine, then we can <span class="red">update the current patch</span> with
<strong>hg qrefresh</strong> to reflect the changes:</p>
<div class="highlight-python"><pre>hg qrefresh</pre>
</div>
<p>No changes are shown anymore by <strong>hg status</strong> or <strong>hg diff</strong>:</p>
<div class="highlight-python"><pre>hg status
hg diff</pre>
</div>
<p>Modifications are now in the patch. See <strong>hg qstatus</strong> or <strong>hg qdiff</strong>:</p>
<div class="highlight-python"><pre>hg qstatus
hg qdiff</pre>
</div>
</div>
<div class="section" id="export-a-patch">
<h3>14. Export a patch<a class="headerlink" href="#export-a-patch" title="Permalink to this headline">¶</a></h3>
<p><span class="red">Add a commit message</span> to the patch:</p>
<div class="highlight-python"><pre>hg qrefresh -m "#12345: add a useless print in the inverse method of a permutation"</pre>
</div>
<p>Export the patch with <strong>hg export</strong>:</p>
<div class="highlight-python"><pre>hg export trac_12345-add_useless_print-sl.patch &gt;
         ~/Documents/tmp/trac_12345-add_useless_print-sl.patch</pre>
</div>
<p>The command <strong>hg export</strong> also adds informations in the patch (author name, date, ...).</p>
<div class="small container">
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Personnaly, I added the following alias to my <tt class="docutils literal"><span class="pre">~/.bashrc</span></tt>:</p>
<div class="last highlight-python"><pre>alias qtoptotmp='hg export `hg qtop` &gt; ~/Documents/tmp/`hg qtop`'</pre>
</div>
</div>
</div>
</div>
<div class="section" id="verify-the-content-the-patch">
<h3>15. Verify the content the patch<a class="headerlink" href="#verify-the-content-the-patch" title="Permalink to this headline">¶</a></h3>
<p>Here is an example of a patch exported by Mercurial for the imaginary ticket
#12345. It contains information about the <span class="red">author</span>, the <span class="red">date</span>, the
<span class="red">commit message</span> we just wrote and finally the complete <span class="red">diff</span>.</p>
<p><strong>trac_12345-add_useless_print-sl.patch</strong>:</p>
<div class="tiny maroon container">
<div class="highlight-python"><pre># HG changeset patch
# User Sebastien Labbe &lt;hidden adress email&gt;
# 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</pre>
</div>
</div>
</div>
<div class="section" id="upload-the-patch-on-sage-trac">
<h3>16. Upload the patch on Sage trac<a class="headerlink" href="#upload-the-patch-on-sage-trac" title="Permalink to this headline">¶</a></h3>
<p><strong>Upload the patch on Sage trac</strong></p>
<blockquote>
<p>You can mention things like <em>&#8220;tested on sage-4.6.1&#8221;</em>
in the text box when uploading the ticket.</p>
<p>Make sure the patch was correctly uploaded by <span class="red">looking at it</span> directly on the web page.</p>
</blockquote>
<p><strong>Set the ticket to needs review</strong></p>
<blockquote>
You may ask somebody to review your ticket.</blockquote>
</div>
<div class="section" id="more-on-mercurial-queues">
<h3>17. More on Mercurial queues<a class="headerlink" href="#more-on-mercurial-queues" title="Permalink to this headline">¶</a></h3>
<p>Other useful Mercurial commands when patches multiplies:</p>
<dl class="docutils">
<dt><strong>hg qnew</strong></dt>
<dd>Create a new patch</dd>
<dt><strong>hg qnew</strong></dt>
<dd>...</dd>
<dt><strong>hg qpop</strong></dt>
<dd>Move a patch from the applied stack to the unapplied one</dd>
<dt><strong>hg qpush</strong></dt>
<dd>Move a patch from the unapplied stack to the applied one</dd>
<dt><strong>hg qtop</strong></dt>
<dd>Show the current patch</dd>
<dt><strong>hg qseries</strong></dt>
<dd>Print all of the patches in order</dd>
</dl>
</div>
<div class="section" id="dowload-a-patch">
<h3>18. Dowload a patch<a class="headerlink" href="#dowload-a-patch" title="Permalink to this headline">¶</a></h3>
<p>A feature available on a Sage Trac ticket interests you? You want to review a
ticket?</p>
<p><span class="red">Download a patch!</span></p>
<p>Insert a patch into the series after the last applied patch with <strong>hg qimport</strong>:</p>
<div class="highlight-python"><pre>hg qimport ~/Downloads/trac_65321-nice-feature-AA.patch</pre>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do <span class="red">NOT</span> use the command <strong>hg import</strong> as it will import the changes
in the current patch.</p>
</div>
</div>
<div class="section" id="edit-the-series-file">
<h3>19. Edit the series file<a class="headerlink" href="#edit-the-series-file" title="Permalink to this headline">¶</a></h3>
<p>You can change the order in which the patches are applied. To do so, simply
edit the <strong>series</strong> file:</p>
<div class="maroon tiny container">
<div class="highlight-python"><pre>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</pre>
</div>
</div>
<p>Make sure the patch you are reviewing is <span class="red">the first patch</span> to be applied:</p>
<div class="maroon tiny container">
<div class="highlight-python"><pre>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</pre>
</div>
</div>
<div class="small container">
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<div class="last line-block">
<div class="line">Patches <span class="red">might not commute</span>, for example if they edit the exact same line.</div>
<div class="line">If conflicts occur after editing the series file and doing <strong>hg
qpush</strong>, simply edit the series file and try again.</div>
</div>
</div>
</div>
</div>
<div class="section" id="reviewing-a-patch">
<h3>20. Reviewing a patch<a class="headerlink" href="#reviewing-a-patch" title="Permalink to this headline">¶</a></h3>
<p>Visit the <a class="reference external" href="http://www.sagemath.org/doc/developer/walk_through.html#reviewing-a-patch">Reviewing a patch</a>
Section of the Sage Developer&#8217;s Guide. Also, make sure you read William Stein&#8217;s
<a class="reference external" href="http://sagemath.blogspot.com/2010/10/how-to-referee-sage-trac-tickets.html">blog post</a>
about reviewing a Sage trac ticket.</p>
<dl class="docutils">
<dt>Make sure the patch applies on Sage without conflicts:</dt>
<dd><tt class="docutils literal"><span class="pre">hg</span> <span class="pre">qpush</span></tt> and <tt class="docutils literal"><span class="pre">hg</span> <span class="pre">qpop</span></tt></dd>
</dl>
<p>Experiment the functionality proposed in the patch.</p>
<ul class="simple">
<li>Make sure the bug described in the ticket is fixed.</li>
<li>Make sure the patch does not introduce any new bug.</li>
</ul>
<dl class="docutils">
<dt>Run tests on the affected files.</dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-t</span> <span class="pre">&lt;affected_files&gt;</span></tt></dd>
</dl>
</div>
<div class="section" id="id4">
<h3>20. Reviewing a patch<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt>Test the entire Sage library.</dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">--testall</span> <span class="pre">--long</span></tt></dd>
<dt>Ensure that the documentation builds fine:</dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-docbuild</span> <span class="pre">reference</span> <span class="pre">html</span></tt></dd>
<dt>Check for full 100% doctest coverage:</dt>
<dd><tt class="docutils literal"><span class="pre">sage</span> <span class="pre">-coverage</span> <span class="pre">&lt;file&gt;</span></tt></dd>
</dl>
<p>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.</p>
</div>
<div class="section" id="positive-review-or-needs-work">
<h3>21. Positive review or Needs work<a class="headerlink" href="#positive-review-or-needs-work" title="Permalink to this headline">¶</a></h3>
<p>Three cases may happen:</p>
<dl class="docutils">
<dt><strong>Needs work</strong></dt>
<dd>Mark it as <strong>needs work</strong> if there is anything to do.</dd>
<dt><strong>Positive review</strong></dt>
<dd>Otherwise, mark it as positive review, and mention in a comment all the
things you checked.</dd>
<dt><strong>Delegate</strong></dt>
<dd>If you don’t feel experienced enough for that, add a comment on the Trac page
explaining what you have checked, what the results were, and that you think
someone more experienced should take a look.</dd>
</dl>
</div>
<div class="section" id="id5">
<h3>21. Positive review or Needs work<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<div class="last line-block">
<div class="line">In Sage, a <strong>negative review</strong> <span class="red">does not</span> exist!</div>
<div class="line">There is always place for work and improvement!</div>
</div>
</div>
</div>
<div class="section" id="do-some-cleaning">
<h3>22. Do some cleaning<a class="headerlink" href="#do-some-cleaning" title="Permalink to this headline">¶</a></h3>
<p>Delete an (unapplied) patch from the queue:</p>
<div class="highlight-python"><pre>hg qdelete trac_65321-nice-feature-AA.patch</pre>
</div>
<p>Erase your branch. Of course, do this only if you don&#8217;t care about your local
changes:</p>
<div class="highlight-python"><pre>rm -rf sage-slabbe</pre>
</div>
</div>
<div class="section" id="references">
<h3>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://www.sagemath.org">Sage</a></p>
<p><a class="reference external" href="http://trac.sagemath.org">Sage trac</a></p>
<p><a class="reference external" href="http://www.sagemath.org/doc/developer/index.html">Sage Developer&#8217;s Guide</a></p>
<p><a class="reference external" href="http://sagemath.blogspot.com/2010/10/how-to-referee-sage-trac-tickets.html">Reviewing a Sage trac ticket</a>,
William Stein&#8217;s blog post, October 31, 2010.</p>
<p>This talk was generated</p>
<ul class="simple">
<li>by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a></li>
<li>from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReStructuredText</a> source</li>
<li>to a <a class="reference external" href="http://docutils.sourceforge.net/docs/user/slide-shows.html">Simple Standards-based Slide Show System (S5)</a> format.</li>
</ul>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference internal" href="#">How to contribute to Sage</a><ul>
<li><a class="reference internal" href="#s-bastien-labb">Sébastien Labbé</a><ul>
<li><a class="reference internal" href="#gnu-general-public-licence">GNU General Public Licence</a></li>
<li><a class="reference internal" href="#twenty-two-easy-steps">Twenty Two Easy Steps</a></li>
<li><a class="reference internal" href="#find-a-bug">1. Find a bug</a></li>
<li><a class="reference internal" href="#sage-trac-server">2. Sage trac server</a></li>
<li><a class="reference internal" href="#create-a-ticket">3. Create a ticket</a></li>
<li><a class="reference internal" href="#clone-your-version-of-sage">4. Clone your version of Sage</a></li>
<li><a class="reference internal" href="#mercurial">5. Mercurial</a></li>
<li><a class="reference internal" href="#id2">5. Mercurial</a></li>
<li><a class="reference internal" href="#enable-mercurial-queues">6. Enable Mercurial queues</a></li>
<li><a class="reference internal" href="#create-an-empty-patch">7. Create an empty patch</a></li>
<li><a class="reference internal" href="#fix-the-bug">8. Fix the bug</a></li>
<li><a class="reference internal" href="#view-your-changes">9. View your changes</a></li>
<li><a class="reference internal" href="#test-the-changes">10. Test the changes</a></li>
<li><a class="reference internal" href="#run-tests">11. Run tests</a></li>
<li><a class="reference internal" href="#build-the-documentation">12. Build the documentation</a></li>
<li><a class="reference internal" href="#update-the-current-patch">13. Update the current patch</a></li>
<li><a class="reference internal" href="#export-a-patch">14. Export a patch</a></li>
<li><a class="reference internal" href="#verify-the-content-the-patch">15. Verify the content the patch</a></li>
<li><a class="reference internal" href="#upload-the-patch-on-sage-trac">16. Upload the patch on Sage trac</a></li>
<li><a class="reference internal" href="#more-on-mercurial-queues">17. More on Mercurial queues</a></li>
<li><a class="reference internal" href="#dowload-a-patch">18. Dowload a patch</a></li>
<li><a class="reference internal" href="#edit-the-series-file">19. Edit the series file</a></li>
<li><a class="reference internal" href="#reviewing-a-patch">20. Reviewing a patch</a></li>
<li><a class="reference internal" href="#id4">20. Reviewing a patch</a></li>
<li><a class="reference internal" href="#positive-review-or-needs-work">21. Positive review or Needs work</a></li>
<li><a class="reference internal" href="#id5">21. Positive review or Needs work</a></li>
<li><a class="reference internal" href="#do-some-cleaning">22. Do some cleaning</a></li>
<li><a class="reference internal" href="#references">References</a></li>
</ul>
</li>
</ul>
</li>
</ul>

            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/demo-how-to-contribute.txt" rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index">index</a></li>
  
    
      <a href="../index.html"><img src="_static/sagelogo.png" style="vertical-align: middle" title="Sage Logo"></a>
    
  
  
        <li><a href="index.html">Thematic Tutorials v4.7.rc0</a> &raquo;</li>
 
      </ul>
    </div>
    
    <div class="footer">
        &copy; Copyright 2005--2011, The Sage Development Team.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.4.
    </div>
    <script type="text/javascript">
/*global jQuery, window */
/* Sphinx sidebar toggle.  Putting this code at the end of the body
 * enables the toggle for the live, static, and offline docs.  Note:
 * sage.misc.html.math_parse() eats jQuery's dollar-sign shortcut. */
var jq = jQuery;  
jq(document).ready(function () {
    var bar, bod, bg, fg, key, tog, wid_old, wid_new, resize, get_state, set_state;
    bod = jq('div.bodywrapper');
    bar = jq('div.sphinxsidebar');
    tog = jq('<div class="sphinxsidebartoggle"></div>');
    
    /* Delayed resize helper.  Not perfect but good enough. */
    resize = function () {
        setTimeout(function () {
            tog.height(bod.height());
        }, 100);
    };
    jq(window).resize(function () {
        resize();
    });
    
    /* Setup and add the toggle. See Sphinx v0.5.1 default.css. */
    fg = jq('div.sphinxsidebar p a').css('color') || 'rgb(152, 219, 204)';
    bg = jq('div.document').css('background-color') || 'rgb(28, 78, 99)';
    wid_old = '230px';
    wid_new = '5px';
    tog.css('background-color', bg)
        .css('border-width', '0px')
        .css('border-right', wid_new + ' ridge ' + bg)
        .css('cursor', 'pointer')
        .css('position', 'absolute')
        .css('left', '-' + wid_new)
        .css('top', '0px')
        .css('width', wid_new);
    bod.css('position', 'relative');
    bod.prepend(tog);
    resize();
    
    /* Cookie helpers. */
    key = 'sphinxsidebar=';
    set_state = function (s) {
        var date = new Date();
        /* Expiry in 7 days. */
        date.setTime(date.getTime() + (7 * 24 * 3600 * 1000));
        document.cookie = key + encodeURIComponent(s) + '; expires=' +
            date.toUTCString() + '; path=/';
    };
    get_state = function () {
        var i, c, crumbs = document.cookie.split(';');
        for (i = 0; i < crumbs.length; i += 1) {
            c = crumbs[i].replace(/^\s+/, '');
            if (c.indexOf(key) === 0) {
                return decodeURIComponent(c.substring(key.length, c.length));
            }
        }
        return null;
    };
    
    /* Event handlers. */
    tog.mouseover(function (ev) {
        tog.css('border-right-color', fg);
    }).mouseout(function (ev) {
        tog.css('border-right-color', bg);
    }).click(function (ev) {
        if (bod.hasClass('wide')) {
            bod.removeClass('wide');
            bod.css('margin-left', wid_old);
            bar.css('width', wid_old);
            bar.show();
            set_state('visible');
        } else {
            set_state('hidden');
            bar.hide();
            bar.css('width', '0px');
            bod.css('margin-left', wid_new);
            bod.addClass('wide');
        }
        resize();
    });
    
    /* Hide the normally visible sidebar? */
    if (get_state() === 'hidden') {
        tog.trigger('click');
    } else {
        set_state('visible');
    }
});
    </script>