Differences between revisions 44 and 45
Revision 44 as of 2009-03-11 17:05:12
Size: 14649
Comment:
Revision 45 as of 2009-03-12 16:51:10
Size: 14657
Comment:
Deletions are marked like this. Additions are marked like this.
Line 25: Line 25:
 * The user has access to: http://combinat.sagemath.org/  * The user has access to: http://combinat.sagemath.org/patches/

The Sage-Combinat patch server: step by step instructions

This page is meant as a step-by-step tutorial on using the Sage-Combinat patch server, from basic installation to contributing new patches:

For technical background on the patch server, see http:/combinat/Mercurial.

To do: add a link to a short write up about the rationale for using a patch server.

1. Installation and basic usage

1.1. Prerequisites

*WARNING*: The sage-combinat server is finaly being moved to its final official destination!

1.1.1. New server, for Sage >= 3.4

The instructions below assume that:

  • Sage 3.4 or higher is already installed (say in /opt/sage), and can be started by typing sage at the command line

    • (it is recommended to use the most recent stable version)
  • The user has write access to the Sage installation tree

  • The user has access to: http://combinat.sagemath.org/patches/

Notes:

  • As of March 11th, Sage 3.4 is not yet officially released (this should come very shortly). In the mean time, you can download the release candidate from:
  • Developpers should be using this server.
  • For simplicity, the server is currently configured with open read-write access (no login/password required). Please do not abuse.

1.1.2. Old read-only server, for Sage < 3.4

The instructions below that:

  • Sage 3.2 or 3.3 is already installed (say in /opt/sage), and can be started by typing sage at the command line.

  • The user has write access to the Sage installation tree

  • The user has access to: http://sage.math.washington.edu:2144/

1.1.3. Mercurial configuration

The patch management is based on the version control system Mercurial, with a support script sage -combinat for ease of use. Online help on this script is accessible through:

sage -combinat --help

Mercurial requires some configuration. Open (or create, if it does not exist yet) your Mercurial configuration file (~/.hgrc in your home directory), insert the following, and edit the username:

[ui]
username = Simon Cussonnet <Simon.Cussonnet at lycee-technique.torrez.eure.fr>
[extensions]
hgext.mq =
extdiff =
alias =
[alias]
qstatus = status --rev -2:.
[hooks]
pre-qrefresh = (echo "Are you sure you want to refresh the following changes:"; sage -hg status; echo -n "into the patch: "; sage -hg qtop; read -p "(y/n)" answer; test "$answer" = "y"  )
[extdiff]
cmd.interdiff = hg-interdiff

1.2. Downloading and installing the Sage-combinat patches

sage -combinat install

1.3. Updating the Sage-Combinat patches

To update the Sage-Combinat patches to the latest version, you can run:

sage -combinat update

It is possible to simultaneously upgrade Sage to the latest version, for now, it is more safe to run both:

sage -upgrade
sage -combinat upgrade

1.4. Uninstalling the Sage-combinat patches

sage -b main

Now, you may destroy .../sage/devel/sage-combinat/ (after checking that you do not have local changes!)

2. Looking and selecting the patches

2.1. The Sage-combinat stack of patches

Sage-combinat is a collection of experimental patches (i.e. extensions) on top of Sage. Each patch describes a relatively atomic modification which may span several files; it may fix a bug, implement a new feature, improve some documentation, ... Here is an example of a patch:

diff -r 01fabd9b3951 sage/combinat/subword.py
--- a/sage/combinat/subword.py
+++ b/sage/combinat/subword.py
@@ -34,7 +34,8 @@

 def Subwords(w, k=None):
     """
-    Returns the combinatorial class of subwords of w.
+    Returns the combinatorial class of subwords of w. The word w can be given
+    by either a string or a list.

     If k is specified, then it returns the combinatorial class
     of subwords of w of length k.

It reads as follows: the first four lines tells that this patch modifies the file sage/combinat/subword.py. The line starting with - is replaces by the two lines starting with +. To be able to apply the modifications safely at the right place, some context information is also stored (ie: some more unmodified lines and the position of the modification into the file).

The patches are organized as a (totally ordered) stack, each being applied on top of the previous one. The most stable are at the bottom, while the most experimental ones are on top. Let's look at a typical stack of patches:

sage -hg qseries

It will display something like:

sage-3.1.3.patch
sage-3.2.patch
...
lazy_attributes-4371-nt.patch
copy_on_write_fh.patch
discrete_function-nt.patch
crystals_alcove_path_model_bj.patch
words_new_fcts_sl.patch

sage-3.1.3 is at the bottom of the stack, and is applied first, while words_new_fcts_sl.patch is applied last. The patch sage-3.2.patch contains all the sage-combinat patches that have readilly been integrated in sage 3.2 (see "using sage-combinat with older versions of sage"). The patch lazy_attributes-4371-nt.patch is about lazy attributes, related to ticket number 4371 on Sage trac, and is owned by NicolasThiéry (nt).

In practice, the stack of patches is managed as a Mercurial queue. The command sage -hg calls the version of Mercurial that comes with Sage. You may instead simply use hg if Mercurial is installed natively on your system.

2.2. Top, applied and unapplied patches

It is possible to move up and down the stack, applying only the patches up to a given one.

sage -hg qpush             # Apply the first patch in the series which is not currently applied
sage -hg qpop              # Unapply the most recently applied patch
sage -hg qpush -a          # Apply all the patches
sage -hg qpop -a           # Unapply all the patches

If you get confused, the following can tell you which patches are applied or not:

sage -hg qtop              # Top applied patch
sage -hg qapplied          # Currently applied patches
sage -hg qunapplied        # Currently unapplied patches

Note that after moving around the stack of patches, it is necessary to rebuild sage before using it :

sage -b
sage

2.3. Looking inside patches

The content of the current top patch can be retrieved with

sage -hg qdiff

while a brief summary of the modifed files is given by

sage -hg qstatus

2.4. Using the sage-combinat patches with an older version of sage

For the convenience of the user, it is usually possible to use the sage-combinat patches with older versions of sage. The intent is only to temporarily support one or two older versions of sage (that is about one month old). Typical use case: a developper urgently needs the latest version of a patch for a software demonstration at a conference, but can't instantly upgrade because of a slow internet connection. There is no guarantee whatsoever; on occasion we do not support this when this causes technical difficulties.

This is the purpose of the patches like sage-3.0.2.patch. This particular patch contains all the sage-combinat patches that have been integrated into Sage 3.0.2, and is only applied if Sage's version is strictly less than 3.0.2. This is achieved through guards (see the next section), and is taken care of automatically by sage -combinat, and in particular by:

sage -combinat qselect

2.5. Selecting guarded patches

Some patches may be guarded since they are experimental, not yet finished, or should be only applied for certain versions of sage. Guarded patches are not applied unless explicitly chosen. For example if one would like to apply patches labeled [+experimental] one can use the following steps:

sage -hg qselect experimental
sage -combinat qselect

Then reapply the appropriate patches, typically with:

sage -hg qpop -a
sage -hg qpush -a

To disregard all guarded patches one uses instead:

sage -hg qselect -n
sage -combinat qselect

3. Creating and contributing patches

3.1. Patch naming convention

Each patch should be of the form:

    <theme>_<feature/fix>_<trac ref if any>_<rev if any>_<owner or final or closed>.patch 

Examples:

root-systems-lattices_nt.patch 
partitions_fix_3244_mh.patch 
crystals-affine_as.patch 
free-modules_1_mh.patch 
free-modules_2_mh.patch 
free-modules_final.patch 
dyck-words_closed.patch 

A series of patches like the free_modules one above is intended to be progressively folded together into a single patch free_modules.patch before submission to sage (see patch folding below). The name free_modules_final indicates that the owner of this patch will no longer edit it, and it is ready to be posted to trac. The name *_closed.patch indicates that this patch has been posted to trac and the corresponding ticket has been closed.

3.2. Creating a new patch (qnew)

The first step is to create a new patch. It is easier to create it before doing any modifications to the sage sources. Never modify a patch that you do not own.

sage -hg qnew my_improvement_ab.patch

where ab are your initials. The new patch is created on top of the most recently applied patch. You may use qpush and qpop first to choose where your patch is created.

3.3. Editing the Sage sources

It is recommended to double check that the current top patch is yours and is the one you want to add your modifications to (see qtop and qpop/qpush). using qpop and qpush become tricky to use once you started modifications.

Now you can edit the Sage sources files to your taste in $SAGE_ROOT/devel/sage-combinat/sage/. At any time, you can review your modifications since the creation of the patch (or since the last qrefresh, see below) by doing:

sage -hg diff           #complete modifications since last qrefresh
sage -hg status         #list the modified files since last qrefresh

If you added a new source file, you must declare it using the command:

sage -hg add <filename>

3.4. Refreshing your patch (qrefresh)

Currently, the modifications are still not part of the patch as may be seen with the commands

sage -hg qdiff
sage -hg qstatus

Use

sage -hg qrefresh

to put the actual modifications in the current top patch. You can check that they have been included in the patch with:

sage -hg qdiff
sage -hg qstatus

Also, they should appear anymore in:

sage -hg diff
sage -hg status

After qrefresh, you can use qpop and qpush again and modify the same patch or some other patch you already created.

3.5. Removing a patch

In case you want to discard your patch, you may use:

sage -hg qremove my_improvement_AB.patch

You may use

sage -hg qseries

to confirm that the patch is removed.

3.6. Pushing patches to the sage-combinat server

Go to the sage-combinat directory, and make sure that there is no local changes:

cd $SAGE_ROOT/devel/sage-combinat
sage -hg status

Otherwise dicard them (sage -hg revert) or save them in your favorite patch (sage -hg qrefresh).

Pull the latest version of the patches from the server, and make sure that everything is working fine after applying all patches:

sage -combinat update -f
sage -hg qpush -a
sage -br  # Make sure this works
sage -t filenames # If you believe your tests should pass, check them.

The -f is to tell sage -combinat to run even if your patch directory is modified, which it probably is.

When pulling from the server, your changes will be merged with those from the server. You may get conflicts in the series file, or patches that do not apply anymore. Fix the patches that you own, and get in touch with the owners of the other broken patches.

When everything is ready, double check that you are up to date:

sage -combinat update -f

and then:

cd $SAGE_ROOT/devel/sage-combinat/.hg/patches
sage -hg commit
sage -hg push

In case you have been unlucky, and there has been a change on the patch server between your last pull and your commit, push will fail with an error like "abort: push creates new remote heads! did you forget to merge?". You then have to merge your local modifications with the remote ones:

cd .hg/patches
sage -hg pull -u
sage -hg merge

If the merge goes through automatically, just commit with "Merge" as message, and push. Otherwise, well, feel free to ask for help!

3.7. Exporting Patches for use with trac

When a patch is ready to be applied to Sage, you should first verify that it will apply cleanly. If you want to be able to undo anything you do in this step, you should run sage -hg qcommit  before beginning.

The first step is, from the PATCHES directory, manually edit the series  to move your patch in the queue, so that your patch (or patches) are applied only to patches labelled *_closed. Then (from the source directories) use qpush and qpop to bring the first of your patches to the top of the stack (ie, only one of your patches should be applied). Suppose your patches were called 1.patch and 2.patch, and you currently have 1.patch at the top of the stack, and 2.patch as the next patch to be applied. The command sage -hg qfold 2.patch will incorporate the changes from 2.patch into 1.patch, and then delete 2.patch. You should repeat this process until all patches working on one particular issue have been incorporated.

Then you should make sure that sage builds, runs, and passes tests, with just this patch applied only to patches that have already been closed. Don't forget to also commit and push your changes to the server.

The next step is to export your patch for submission. Running "sage -hg export" includes extra information in the patch such as the author of the patch.

cd $SAGE_ROOT/devel/sage-combinat
sage -hg export new_feature.patch > /path/to/new_feature_for_trac.patch

You would then upload the file new_feature_for_trac.patch to the appropriate ticket on the Sage Trac server, creating the ticket if necessary. Procedures for using the trac system are described here: http://wiki.sagemath.org/TracGuidelines

combinat/MercurialStepByStep (last edited 2014-07-20 19:38:35 by chapoton)