Differences between revisions 23 and 26 (spanning 3 versions)

The Sage-combinat patch server: step by step instructions

This page describes how to install and update the Sage-combinat experimental patches.

See also the step by step instructions to contribute to sage-combinat.

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

Contents

Installation and basic usage
Looking and selecting the patches
Creating and contributing patches

1. Installation and basic usage

1.1. Prerequisites

We assume that:

Sage 3.2 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 on the Sage installation tree
The user has access to: http://sage.math.washington.edu:2144/

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: "; hg qtop; read -p "(y/n)" answer; test "$answer" = "y"  )
[extdiff]
cmd.interdiff = hg-interdiff

1.2. Get usage information

sage -combinat --help

1.3. Download and install the Sage-combinat patches

sage -combinat install

1.4. Update the Sage-combinat patches

sage -combinat update

1.5. Upgrade Sage and update the Sage-combinat patches

sage -combinat upgrade

1.6. Uninstall 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, ...

TODO: insert a short example here:

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, whil

Technically, they are managed as a Mercurial queue. Let's look at a typical stack of patches:

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. Up to some point, it allows for using the later patches on 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 Nicolas Thiéry (nt).

2.2. Top, applied and unapplied patches

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

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

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

hg qtop               # Top applied patch
hg qapplied         # Currently applied patches
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

hg qdiff

while a brief summary of the modifed files is given by

hg qstatus

2.4. Selecting guarded patches

Some patches may be guarded since they are experimental, not yet finished, or used for different 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:

hg qselect experimental
sage -combinat qselect

Then reapply the appropriate patches, typically with

hg qpop -a
hg qpush -a

To disregard all guarded patches one uses instead:

hg qselect -n== Using the sage-combinat patches with an older version of sage ==
For the convenience of the user, it is possible to use the sage-combinat patches with an older version of sage. For this, one needs to specify that the sage-combinat patches that were integrated into the latest sage version (and therefore are not applied by default) need to be applied. The intent is only to temporarily support one or two older versions of sage (that is about one month old); there is no guarantee whatsoever.

Note: this is taken care of automatically when using the sage-combinat script for installing or upgrading
sage -combinat qselect

3. Creating and contributing patches

3.1. Creating a patch

Note that a patch has a unique owner so you should only modify a patch that is already yours.

Changes always go to the actual top patch currently applied. So before doing any changes, you must determine the patch where the changes should be saved. If it is your first contribution, start by creating a patch:

$ hg qpush -a                      #facultatif
$ hg qnew my_improvement_AB.patch

The line hg qpush -a is only to make sure that the new patch is be created on top of the stack, because qnew creates a new patch right after the most recently applied patch. It is suggested to add your initials (here AB) in the name so that everybody knows who owns what. TODO : Add more details about naming of patch.

3.2. Do your modifications

Before making any modifications, make sure the current top patch is yours and is the one you want to add your modifications to. (see qpop and qpop/qpush). "'Caveat: using qpop and qpush become tricky to use once you started modifications.'"

$ hg qtop                     #to print the current top patch
$ hg qpop
$ hg qpush                    #to change the top patch currently applied

Once you set the current top patch to the one you want, do your modifications to one or many existing files. At any time, you can review your modifications done since the last qrefresh (explained below) or since the creation of the patch by doing:

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

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

$ hg add <filename>

3.3. Refreshing your patch (qrefresh)

Currently, the modifications are still not part of the patch as seen by the command

hg qdiff
hg qstatus

that does not display them. Use

hg qrefresh

to put the actual modifications in the current top patch. You can see that it worked when typing the command

hg qdiff
hg qstatus

that should now include your modifications and by the command

hg diff
hg status

that should not display them anymore.

3.4. Do more modifications

After qrefresh, you can now use qpop and qpush again and modify the same or other patches you already created. See steps 3-7.

3.5. Remove a patch

It is possible that you want to remove one of your patch from the stack. For example, you may have created a patch while reading these lines put don't want it to get in the sage-combinat server :

$ hg qremove my_improvement_AB.patch

You may use

$ 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 (hg status); otherwise dicard them (hg revert) or save them in your favorite patch (hg qrefresh).

cd $SAGE_ROOT/devel/sage-combinat
hg status

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

sage -combinat update -f
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 .hg/patches
hg commit
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 .ht/patches
hg pull -u
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 hg qcommit before beginning.

The first step is, from the PATCHES directory, manually edit the series file 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 $ 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 "hg export" includes extra information in the patch such as the author of the patch.

cd $SAGE_ROOT/devel/sage-combinat
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

-  ⇤ ← Revision 23 as of 2009-01-26 21:48:20 → 
  Size: 1878
  Editor: slabbe
  Comment:
+   ← Revision 26 as of 2009-01-28 17:27:31 → ⇥
  Size: 11584
  Editor: NicolasThiery
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-= The Sage-combinat patch server: basic instructions =
+#pragma section-numbers 2

= The Sage-combinat patch server: step by step instructions =
-Line 6:
+Line 9:
-For advanced usage of the patch server, see http:/combinat/Mercurial.

<<TableOfContents(2)>>

== Prerequisites ==
+For technical background on the usage of the patch server, see http:/combinat/Mercurial.

<<TableOfContents(3)>>

== Installation and basic usage ==

=== Prerequisites ===
-Line 13:
+Line 18:
- * Sage is already installed (say in /opt/sage)
 * Mercurial is already installed (sudo apt-get install Mercurial on Debian)
 * The user has write access on the Sage installation tree
+ * Sage 3.2 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 on the {{{Sage}}} installation tree
-Line 17:
+Line 22:
-It can be possible that the Mercurial configuration file hasn't being created during the installation of Mercurial, you will have to create it and edit it before to install Sage-combinat.
Open your Mercurial configuration file (~/.hgrc in your home directory), insert the following, and edit the username:
+/* * Mercurial is already installed ({{{sudo apt-get install mercurial}}} on Debian) */

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:
-Line 35:
+Line 41:
-== Download and install the Sage-combinat patches ==
+=== Get usage information ===
{{{
sage -combinat --help
}}}

=== Download and install the Sage-combinat patches ===
-Line 41:
+Line 51:
-Some help is available with:
{{{
sage -combinat --help
}}}

== Update the Sage-combinat patches ==
+=== Update the Sage-combinat patches ===
-Line 51:
+Line 56:
-== Upgrade Sage and update the Sage-combinat patches ==
+=== Upgrade Sage and update the Sage-combinat patches ===
-Line 56:
+Line 61:
-== Uninstall the Sage-combinat patches ==
+=== Uninstall the Sage-combinat patches ===
-Line 61:
+Line 66:
+== Looking and selecting the patches ==

=== 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, ...

TODO: insert a short example here:

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, whil


 Technically, they are managed as a Mercurial queue. Let's look at a typical stack of patches:
{{{
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.
Up to some point, it allows for using the later patches on older versions of sage.
The patch lazy_attributes-4371-nt.patch is about lazy attributes, related to [[http://sagetrac.org/sage_trac/ticket/4371|  ticket number 4371 on Sage trac]], and is owned by Nicolas Thiéry (nt).

=== Top, applied and unapplied patches ===

It is possible to move up and down the stack, applying all the patches up to a given one.
{{{
hg qpush             # Apply the first patch in the series which is not currently applied
hg qpop              # Unapply the most recently applied patch
hg qpush -a          # Apply all the patches
hg qpop -a           # Upapplied all the patches
}}}

If you get confused, the following can tell you which patches are applied or not:
{{{
hg qtop               # Top applied patch
hg qapplied         # Currently applied patches
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
}}}

=== Looking inside patches ===

The content of the current top patch can be retrieved with
{{{
hg qdiff
}}}
while a brief summary of the modifed files is given by
{{{
hg qstatus
}}}


=== Selecting guarded patches ===
Some patches may be guarded since they are experimental, not yet finished, or used for different 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:

{{{
hg qselect experimental
sage -combinat qselect
}}}
Then reapply the appropriate patches, typically with
{{{
hg qpop -a
hg qpush -a
}}}

To disregard all guarded patches one uses instead:
{{{
hg qselect -n== Using the sage-combinat patches with an older version of sage ==
For the convenience of the user, it is possible to use the sage-combinat patches with an older version of sage. For this, one needs to specify that the sage-combinat patches that were integrated into the latest sage version (and therefore are not applied by default) need to be applied. The intent is only to temporarily support one or two older versions of sage (that is about one month old); there is no guarantee whatsoever.

Note: this is taken care of automatically when using the sage-combinat script for installing or upgrading
sage -combinat qselect
}}}


== Creating and contributing patches ==

=== Creating a patch ===

Note that a patch has a unique owner so you should only modify a patch that is already yours.

Changes always go to the actual top patch currently applied. So before doing any changes, you must determine the patch where the changes should be saved. If it is your first contribution, start by creating a patch:
{{{
$ hg qpush -a                      #facultatif
$ hg qnew my_improvement_AB.patch
}}}
The line {{{hg qpush -a}}} is only to make sure that the new patch is be created on top of the stack, because {{{qnew}}} creates a new patch right after the most recently applied patch. It is suggested to add your initials (here AB) in the name so that everybody knows who owns what. TODO : Add more details about naming of patch.

=== Do your modifications ===

Before making any modifications, make sure the current top patch is yours and is the one you want to add your modifications to.
(see {{{qpop}}} and {{{qpop/qpush}}}). "'Caveat: using {{{qpop}}} and {{{qpush}}} become tricky to use once you started modifications.'"
{{{
$ hg qtop                     #to print the current top patch
$ hg qpop
$ hg qpush                    #to change the top patch currently applied
}}}
Once you set the current top patch to the one you want, do your modifications to one or many existing files. At any time, you can review your modifications done since the last {{{qrefresh}}} (explained below) or since the creation of the patch by doing:
{{{
$ hg diff           #complete modifications since last qrefresh
$ hg status         #list the modified files since last qrefresh
}}}
If you added a file, you must declare it using the command:
{{{
$ hg add <filename>
}}}

=== Refreshing your patch (qrefresh) ===

Currently, the modifications are still not part of the patch as seen by the command
{{{
hg qdiff
hg qstatus
}}}
that does not display them. Use 
{{{
hg qrefresh
}}}
to put the actual modifications in the current top patch. You can see that it worked when typing the command
{{{
hg qdiff
hg qstatus
}}}
that should now include your modifications and by the command
{{{
hg diff
hg status
}}}
that should not display them anymore.

=== Do more modifications ===

After {{{qrefresh}}}, you can now use {{{qpop}}} and {{{qpush}}} again and modify the same or other patches you already created. See steps 3-7.

=== Remove a patch ===

It is possible that you want to remove one of your patch from the stack. For example, you may have created a patch while reading these lines put don't want it to get in the sage-combinat server :
{{{
$ hg qremove my_improvement_AB.patch
}}}
You may use
{{{
$ hg qseries
}}}
to confirm that the patch is removed.

=== Pushing patches to the sage-combinat server ===

Go to the sage-combinat directory, and make sure that there is no local changes (hg status); otherwise dicard them (hg revert)
or save them in your favorite patch (hg qrefresh).
{{{
cd $SAGE_ROOT/devel/sage-combinat
hg status
}}}

Pull the latest version of the patches from the server, and make sure that everything is fine after applying all patches:
{{{
sage -combinat update -f
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 .hg/patches
hg commit
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 .ht/patches
hg pull -u
hg merge
}}}
If the merge goes through automatically, just commit with Merge as message, and push.
Otherwise, well, feel free to ask for help!

=== 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 {{{hg qcommit }}} before beginning.

The first step is, from the {{{PATCHES}}} directory, manually edit the {{{series }}} file 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 {{{$ 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 "hg export" includes extra information in the patch such as the author of the patch.
{{{
cd $SAGE_ROOT/devel/sage-combinat
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

Diff for "combinat/MercurialBasic"