development_for_newbies
system:sage

<h1><span style="font-family: arial,helvetica,sans-serif;">Dev for Newbies!</span></h1>
<p><span style="font-family: arial,helvetica,sans-serif;">This is a worksheet complements the Development for Newbies documentation.&nbsp; </span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">The following are two prerequisits to changing code in Sage and sharing code to the Sage community.&nbsp; Sage comes with a nifty program called the Mercurial which is the source control system that is included with Sage.<br /></span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">1. Before using Mercurial, make sure to define your username so the patches you make are identified as yours. Make a file ~/.hgrc in your home directory like this one:<br /><br />[ui]<br />username =&nbsp; Carl Gauss &lt;cgauss@math.university.edu&gt;</span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">and so you are able to happily use Sage should your code break everything, make a copy to modify:<br /></span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">2.&nbsp; At the command line in the sage directory type: sage -clone namehere, example:<br />~/sage-3.4.alpha0: sage -clone myver<br /></span></p>

<p><span style="font-family: arial,helvetica,sans-serif;">3. Next, go write some code!&nbsp; For example and example ofcode to put in the sage clone, create a function that returns the polynomial of a Quadratic Form.&nbsp; You can first create and text the code in the sage notebook or at the command line.&nbsp; After formatting to the code to Sage standards (see the Development Guide: http://www.sagemath.org/doc/prog/node9.html), save the code as part of the appropriate file. For example take:</span></p>

{{{id=9|
def polynomial(self):
	"""
	Returns the polynomial of the quadratic form in the ring R[X] where X=<x0,x1,...,x(n-1)>
	Input: Q - a quadratic form
        Output: P - the polynomial form of a Quadratic form
	EXAMPLES:
	    sage: Q = DiagonalQuadraticForm(QQ,[1,3,5,7])
	    sage: P = Q.polynomial(); P
	    2*x0^2 + 6*x1^2 + 10*x2^2 + 14*x3^2
	"""
	M = self.matrix()
        n = self.dim()
        R = PolynomialRing(self.base_ring(),'x',n)
        V = vector([R.gens()[i] for i in range(n)])
        P = (M*V).dot_product(V)
        return P
///
}}}

<p><span style="font-family: arial,helvetica,sans-serif;">When you are satisfied with the code, copy it into ~/sage-3.4.alpha0/devel/sage-myver/sage/quadratic_forms/quadratic_forms.py<br /><br />Notice that the above code calls PolynomialRing and vector.&nbsp; Checking the import statements at the top of quadratic_forms.py we see that neither is supported, so we add the following to the import statements<br /><span style="font-family: courier new,courier;">##===============================================================================<br />from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing<br />from sage.modules.free_module_element import vector<br />##===============================================================================</span><br /></span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">For the first, to find the correct path, at the Sage command line or in you notebook type:<br /><span style="font-family: courier new,courier;">PolynomialRing?? &lt;shift&gt;+&lt;enter&gt;</span><br />The top line gives the file, just use the path beginning at sage and follow the above syntax.</span></p>

{{{id=8|
PolynomialRing??
///
}}}

<p><span style="font-family: arial,helvetica,sans-serif;">Now you need to build your copy of sage with these changes.&nbsp; Go to <br /><span style="font-family: courier new,courier;">~/Desktop/sage-*.*.*</span><br />and run<span style="font-family: courier new,courier;"> sage -b myver</span> (or <span style="font-family: courier new,courier;">sage -br myver</span> to run sage-myver on completion)<br />i.e.&nbsp; </span><span style="font-family: arial,helvetica,sans-serif;"><span style="font-family: courier new,courier;">~/Desktop/sage-3.4.alpha0:$ </span><span style="font-family: courier new,courier;">./sage -br myver</span></span></p>
<p><span style="font-family: arial,helvetica,sans-serif;"><span style="font-family: courier new,courier;"><span style="font-family: arial,helvetica,sans-serif;">This shouldn't take long.<br />Then you can run Sage and try some examples!</span></span></span></p>
<p><span style="font-family: arial,helvetica,sans-serif;"><br />Now comes to the fun part, where you submit your changes to the Sage community, i.e. you submit your code as a patch.<br />This is where we use the Mercurial to produce these patch files.&nbsp; You can use the notebook or the Sage command line.</span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">At the Sage command line type or in a notebook cell:<br /><span style="font-family: courier new,courier;">hg_sage.status()</span><br />which will be followed by<br /><span style="font-family: courier new,courier;">hg_sage.diff()</span><br /></span></p>

{{{id=0|
hg_sage.status()
///
Getting status of modified or unknown files:
cd "/home/aly/Desktop/sage-3.4.alpha0/devel/sage" && hg status

---
}}}

{{{id=1|
hg_sage.diff()
///
cd "/home/aly/Desktop/sage-3.4.alpha0/devel/sage" && hg diff  | cat
}}}

<p><span style="font-family: arial,helvetica,sans-serif;">Next commit the changes in the files to the repository. Do this with the command <span style="font-family: courier new,courier;">hg_sage.commit('comment here')</span>.&nbsp; In the notebook you *must* specify a comment.&nbsp; </span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">At the command line, first the output of <span style="font-family: courier new,courier;">hg_diff</span> is displayed: look at it or just enter <span style="font-family: courier new,courier;">q</span>. Then you are dumped into an editor to type a brief comment on the changes. The default editor is vi, so type i, write some meaningful one line description, hit Escape and type <span style="font-family: courier new,courier;">:wq</span>.&nbsp; This also shows your username as given in the file you created previously (see above).&nbsp; Quick note: In bash, to make emacs the default editor, type <span style="font-family: courier new,courier;">export EDITOR=emacs</span> (or whatever you like to use).</span></p>

{{{id=17|
#how do you make this work in the notebook?
#hg_sage.commit()
///
}}}

<p><span style="font-family: arial,helvetica,sans-serif;">Now to finally create a patch, first type</span></p>
<p><span style="font-family: courier new,courier;">hg_sage.log()</span></p>
<p><span style="font-family: courier new,courier;"><span style="font-family: arial,helvetica,sans-serif;">to see your revision number.&nbsp; <br />This is the 5-digit number at the top of the screen following changeset, ie.</span><br />changeset:&nbsp;&nbsp; 11732:5d9f5da78387<br /><span style="font-family: arial black,avant garde;">the revision number here is 11732.</span><br /></span></p>

{{{id=2|
hg_sage.log()
///
cd "/home/aly/Desktop/sage-3.4.alpha0/devel/sage" && hg log -l 20  | cat
changeset:   11732:5d9f5da78387
tag:         tip
user:        Aly Deines <aly.deines@gmail.com>
date:        Mon Mar 02 09:57:32 2009 -0800
summary:     this code gives the polynomial form of a quadratic form

changeset:   11731:c32e1e45a32b
user:        Aly Deines <aly.deines@gmail.com>
date:        Mon Mar 02 09:57:32 2009 -0800
summary:     this code gives the polynomial form of a quadratic form

changeset:   11730:d256368eca93
user:        mabshoff@sage.math.washington.edu
date:        Tue Feb 24 14:18:30 2009 -0800
summary:     3.4.alpha0

changeset:   11729:37c26bf8284d
user:        mabshoff@sage.math.washington.edu
date:        Tue Feb 24 14:18:30 2009 -0800
summary:     Added tag 3.4.alpha0 for changeset f7614d495ff0

changeset:   11728:f7614d495ff0
tag:         3.4.alpha0
user:        mabshoff@sage.math.washington.edu
date:        Tue Feb 24 13:40:22 2009 -0800
summary:     Make various doctests in the new quadratic forms code optional (#4470)

changeset:   11727:6207a0fcd309
user:        Gonzalo Tornaría <tornaria@math.utexas.edu>
date:        Sun Feb 22 22:23:18 2009 -0500
summary:     #4470: many fixes and doctests for quadratic forms code

changeset:   11726:5affcc76eae2
user:        Gonzalo Tornaría <tornaria@math.utexas.edu>
date:        Sun Feb 22 22:15:13 2009 -0500
summary:     #4470: Initial commit of Jon Hanke's quadratic forms code

changeset:   11725:8b77f1f96c8a
user:        Carl Witty <cwitty@newtonlabs.com>
date:        Sun Feb 22 12:39:27 2009 -0800
summary:     __dealloc__ can happen at random times, so it must not have side-effects (fixes #5340)

changeset:   11724:4bc694302363
user:        Carl Witty <cwitty@newtonlabs.com>
date:        Sat Feb 21 19:28:01 2009 -0800
summary:     Looks like a tiny error in rebasing.

changeset:   11723:f5fb0c5f6416
user:        Robert Bradshaw <robertwb@math.washington.edu>
date:        Tue Feb 24 00:13:04 2009 -0800
summary:     Fix trac #5356 -- literals wrapped twice in notebook (negating the 'r' notation)

changeset:   11722:2ff52851ed28
user:        mabshoff@sage.math.washington.edu
date:        Mon Feb 23 07:09:56 2009 -0800
summary:     Make extensions linking against libSingular depend on /Users/michaelabshoff/Desktop/sage-3.3.rc0-libpng12/local/include/libsingular.h (#5349)

changeset:   11721:a9720d066e7a
user:        Carl Witty <cwitty@newtonlabs.com>
date:        Mon Feb 23 18:07:58 2009 -0800
summary:     Pay no attention to the irrelevant RAND_MAX from <stdlib.h>

changeset:   11720:be492f0cd472
user:        Mike Hansen <mhansen@gmail.com>
date:        Tue Feb 24 09:40:37 2009 -0800
summary:     Disable doctests for #5338

changeset:   11719:80b63a6f6ddc
user:        Mike Hansen <mhansen@gmail.com>
date:        Sat Sep 27 20:09:12 2008 -0700
summary:     Fixed #5336: Get the live documentation to work with the new Sphinx HTML documents.

changeset:   11718:f19ce6d95adf
user:        Mike Hansen <mhansen@gmail.com>
date:        Tue Feb 24 09:29:08 2009 -0800
summary:     Trac #5330: Miscellaneous documentation fixes.

changeset:   11717:f902d1a255b5
user:        Mike Hansen <mhansen@gmail.com>
date:        Tue Feb 24 09:29:18 2009 -0800
summary:     Documentation fixes for #4906.

changeset:   11716:f1cf8b52a13f
user:        Carl Witty <cwitty@newtonlabs.com>
date:        Sat Feb 21 19:32:42 2009 -0800
summary:     Something turned some sample code into a non-working doctest; change it back to sample code.

changeset:   11715:22feba95e7f6
user:        Mike Hansen <mhansen@gmail.com>
date:        Tue Feb 24 09:13:34 2009 -0800
summary:     Converting sage.modular.* docstrings to Sphinx

changeset:   11714:08fee8bc2023
user:        Mike Hansen <mhansen@gmail.com>
date:        Tue Feb 24 09:13:34 2009 -0800
summary:     Converting sage.plot.* docstrings to Sphinx

changeset:   11713:82d7ecdc331b
user:        Mike Hansen <mhansen@gmail.com>
date:        Tue Feb 24 09:13:34 2009 -0800
summary:     Converting sage.matrix.* docstrings to Sphinx
}}}

<p><span style="font-family: arial,helvetica,sans-serif;">Then type </span><br />hg_sage.export('revision number here')&nbsp;<span style="font-family: arial,helvetica,sans-serif;"> (make sure to use ' ')</span></p>

{{{id=3|
hg_sage.export('11732')
///
Output will be written to revision numbered file.
cd "/home/aly/Desktop/sage-3.4.alpha0/devel/sage" && hg export  -o "/home/aly/.sage/sage_notebook/worksheets/admin/19/cells/3/%R.patch" 11732
}}}

<p><span style="font-family: arial,helvetica,sans-serif;">Your patch is now located in your sage-*.*.* folder (in this example sage-3.4.alpha0) as revision_number.patch.&nbsp; <br />To see this in the notebook format, use the same commands in the same order, for an example check out the notebook: development_for_newbies<br />If you want to apply a patch file, use the command<span style="font-family: courier new,courier;"> hg_sage.patch('filename')</span>.<br /><br />The next step is to post your patch on the Sage trac server.<br />To post to the trac server you must first get a trac account.&nbsp; To do this: "write an email to michael.abshoff.abc@googlemail.com [remove the abc] and provide an account name and password. The account name should be non-silly, i.e. no first names, no leet-handles. Ideally it should be the first character of your first name together with your last name. It is also recommended that it should be identical or at least close to your Google group's handle. The password currently cannot be changed by the user."<br /><br />Once you have a trac account you can post a patch as a ticket. (First look around and get a feel for the site and how the tickets are written). Click on New Ticket in upper right hand corner.&nbsp; And fill in like so:<br />Create New Ticket:<br />Summary: [with patch, needs review] Quadratic Form polynomial<br />Description: Given a quadratic form Q over the ring R of dimension n, this returns the polynomial form in n variables over R.&nbsp;&nbsp; <br />Type: enhancement&nbsp;&nbsp; Priority: trivial<br />Milestone: sage-3.4.1&nbsp; Component: quadratic forms<br />Keywords: quadratic forms<br />check box: I have files to attach to this ticket<br />then click on the create ticket.<br />The next page allows you to attach the patch.</span></p>
<p><span style="font-family: arial,helvetica,sans-serif;">After attaching the patch you are now a Sage developer!<br /></span></p>
<p>&nbsp;</p>

{{{id=4|

///
}}}

{{{id=5|

///
}}}