|
Size: 13287
Comment:
|
Size: 23107
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 10: | Line 10: |
| To do: add a link to a short write up about the rationale for using a patch server. |
|
| Line 14: | Line 16: |
| 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/ 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: {{{ |
The instructions below assume that: * You need to have a very recent version of Sage already installed (say in {{{/opt/sage}}}) which can be started by typing {{{sage}}} at the command line (it is recommended to use the most recent stable version, and in particular >= 4.3.1 as of 2010, march the 20) * The user has write access to the {{{Sage}}} installation tree * The user has access to: http://combinat.sagemath.org/patches/ With Sage < 4.7.1, if you do not already have an hg configuration file {{{$HOME/.hgrc}}} in your home directory, you need to create such a file containing the following (edit your name!!!): {{{ [ui] username = Simon Cussonnet <Simon.Cussonnet at lycee-technique.thorel.eure.fr> }}} Notes: * 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: {{{ |
| Line 23: | Line 38: |
| }}} 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 }}} |
}}} |
| Line 42: | Line 41: |
| Line 46: | Line 46: |
| ==== Installing the Sage-combinat patches on OS X ==== There occurred several issues installing the Sage-combinat patches on OS X, which have to be solved BEFORE running {{{sage -combinat install}}}. * Have the [[http://developer.apple.com/technologies/tools/|developer tools (XCode)]] installed /* * Have the newest version of gcc installed (update the unix development tools). * gcc must be callable from within the sage folder {{{$SAGEROOT}}}. This can be done by having the path containing gcc (e.g. {{{$HOME/Developer/usr/bin}}}) added to the variable {{{$PATH}}}. * Double-check that you downloaded the appropriate version of Sage (32-bit or 64-bit). */ * Open the file {{{$SAGEROOT/local/bin/sage-check-64}}} in the editor of your choice, and comment out ALL lines starting with "echo" by adding "#" in the beginning of the line. |
|
| Line 57: | Line 72: |
| However, we do recommend installing instead a fresh new version of Sage, and then reinstalling the patches on top of it with {{{sage -combinat install}}}. | |
| Line 68: | Line 84: |
| 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: | 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. Then main information contained in a patch is a {{{diff}}} file which describes the difference between two files. Here is an example of a {{{diff}}} file. |
| Line 84: | Line 100: |
| 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). | It reads as follows: the first four lines tells that this patch modifies the file {{{sage/combinat/subword.py}}}. The line starting with {{{-}}} is replaced 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). |
| Line 134: | Line 150: |
| The content of the current top patch can be retrieved with | The description of a patch can be retrieved with: {{{ sage -hg qheader # top patch sage -ht qheader bla.patch }}} The content of the current top patch can be retrieved with: |
| Line 138: | Line 160: |
| while a brief summary of the modifed files is given by | while the files modified in the top patch can be seen with: |
| Line 143: | Line 165: |
| Warning: {{{ sage -hg qstatus }}} will return irrelevant information if there is no patch currently on top of the stack. |
|
| Line 145: | Line 169: |
| For the convenience of the user, it is possible to use the sage-combinat patches with an older version of sage. 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. 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: |
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 developer 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-4.7.patch}}}. This particular patch contains all the sage-combinat patches that have been integrated into Sage 4.7, and is only applied if Sage's version is strictly less than 4.7. This is achieved through guards (see the next section), and is taken care of automatically by {{{sage -combinat}}}, and in particular by: |
| Line 175: | Line 201: |
| The following conventions are used regarding positive and negative version guards: * A patch marked +4_7 is not applied if sage's version >= 4_7 Use case: patches merged in 4.7 or that need rebase for 4.7 * A patch marked -4_7 is not applied if sage's version < 4_7 Use case: patches that don't apply anymore on old versions * A patch should not be marked with both +4_7 an -4_7. |
|
| Line 178: | Line 213: |
| === Mercurial configuration === Write access to the Mercurial server requires authentication using your Sage's trac account username and password; if you do not yet have a Sage's trac account, create one ([[http://trac.sagemath.org/sage_trac/|instructions]]). Some further configuration is also required. 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, trac username, password, the shortusername* (usually the 2 initials of your first-name/last-name): {{{ [ui] username = Simon Cussonnet <Simon.Cussonnet at lycee-technique.thorel.eure.fr> [auth] combinat_patches.prefix = http://combinat.sagemath.org/patches/ combinat_patches.username = <your username on Sage's trac server> combinat_patches.password = <your password on Sage's trac server> [extensions] hgext.mq = hgext.highlight= hgext.record= extdiff = color= [alias] qstatus = status --rev -2:. # set the shortusername variable to the letters that define your signature on the patches (e.g. 'sc' for Simon Cussonet) [hooks] pre-qrefresh = (shortusername='sc' ; if [[ "$(sage -hg qtop | grep -c "\-$shortusername.patch$")" != "1" ]] ; then echo -e "\\033[01;05;31m* * * * * * * THIS IS NOT YOUR PATCH * * * * * * *\\033[0;0m" ; fi ; 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") pre-import = (if [ -d $(hg root)/.hg/patches ]; then echo "I'm pretty sure that you don't want to import a changeset !"; echo "Do you mean 'hg qimport <patch>' ?"; exit 1; fi) [extdiff] cmd.interdiff = hg-interdiff [diff] nodates=1 showfunc=1 git=1 }}} |
|
| Line 182: | Line 264: |
| <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. |
<trac ref if any>-<theme>_<feature/fix>_<rev if any>-<owner's shortusername or final or closed>.patch }}} Examples: {{{ trac_9557-fundamental_domains-vd.patch sturmian_words_classes-abm.patch trac_5991_dynamic_class-nt.patch trac_7236_partitions_tableaux_cells_cleanup-fh.patch trac_7251_integer_parent-nt.patch trac_7251_integer_parent-review-fs.patch }}} A series of patches like the free_modules one above is intended to be progressively folded together into a single patch trac_7251_integer_parent-nt.patch before submission to sage (see patch folding below). === Patch description === Each patch starts with a description header which is preserved upon {{{hg export}}}. This is the first thing that will be seen by someone opening the patch. Moreover, the first line of this description will end up into the history of Sage (see the output of {{{sage -hg log}}}). So it should be as meaningful as possible, i.e. contain the ticket number associated to the patch and a small description. Typically, this description will match with the summary + description of the (upcoming) trac ticket: {{{ #5431: Free modules: implements blah blah This patch implements ... }}} This description can be edited at any point using {{{hg qrefresh -e}}}, so feel free to update it on a regular basis to include progress information (what has readily been implemented, what remains to be done, etc: {{{ #1234: Permutations: implementation of bruhat order Done: * Added methods succ_bruhat, pred_bruhat, ... Todo: * Add method bruhat_order, ... }}} This is usually at this point that one has the best view of this description. |
| Line 203: | Line 309: |
| 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. |
sage -hg qnew my_improvement_ab.patch -m "#N: description of the patch" }}} where ab are your initials and N is the associated sage trac ticket number if it exists. For a larger description you may want to use the -e option to edit the description with your favorite editor. 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. If you accidentally made changes before creating a new patch, the command {{{ sage -hg qnew -f my_improvement_ab.patch -m "#N: description of the patch" }}} will create the new patch including the current 'orphaned' changes into it. |
| Line 226: | Line 338: |
| sage -hg diff # Completely lists the modifications sage -hg status # Lists only the affected files }}} Note that {{{sage -hg status}}} gives the modifications which are not part of the current patch, while {{{sage -hg qstatus}}} gives the modifications which are part of the current patch (and similarly for {{{diff}}} and {{{qdiff}}}). Use {{{ sage -hg qrefresh }}} to put the actual modifications in the current top patch. Tip: on a regular basis, use also: {{{ sage -hg qrefresh -e }}} OR {{{ sage -hg qrefresh -m "#N: description of the patch" }}} to update the description of the patch, as this usually is the point in time where one has the best view of what it should be. It can also be the opportunity to add the sage trac ticket number to the description if it is created. You can check that the modifications have been included in the patch with: {{{ |
|
| Line 229: | Line 364: |
| 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: |
Also, they should not appear anymore in: |
| Line 265: | Line 391: |
| Otherwise dicard them ({{{sage -hg revert}}}) or save them in your favorite patch ({{{sage -hg qrefresh}}}). | Otherwise discard them ({{{sage -hg revert}}}) or save them in your favorite patch ({{{sage -hg qrefresh}}}). |
| Line 300: | Line 426: |
| Otherwise, well, feel free to ask for help! | Otherwise, read the section Merging conflicts and feel free to ask for help! === In the case of Merging conflicts === In the case of merging conflicts, you should obtain such a message : {{{ TOBEDONE }}} First, use the following to list the files needing a manual merge. If you edited your own patches and nobody edited your patches, only the series file should be listed. If other files are listed, you should definitively ask for help. {{{ cd .hg/patches hg resolve -l #list state of files needing merge (U = unresolve, R = resolved) }}} Open and edit the series file and merge the modifications yourself. Then, when you are done, mark the series file as resolve by doing {{{ hg resolve -m series }}} Make sure the series file is now marked as resolved using: {{{ hg resolve -l #list state of files needing merge (U = unresolve, R = resolved) }}} Then, try to merge again {{{ hg merge }}} and commit if the merge worked: {{{ hg commit }}} You may now try to push again to the sage-combinat server as explain above. === Handling rejection === Sometimes a patch fails to apply and you get, after a {{{ sage -hg qpush }}} a message like : {{{ applying my_modification.patch patching file file_a Hunk #1 FAILED at 0 1 out of 17 hunks FAILED -- saving rejects to file file_a.rej patch failed, unable to continue (try -v) patch failed, rejects left in working dir Errors during apply, please fix and refresh my_modification.patch }}} After such an error, Mercurial has made all modification its can to the file file_a and ''rejects'' the hunk its could not understand. All modifications inside the patch and not understood by Mercurial are in the file file_a.rej created in the working directory (e.g. at the same place that file_a is). The rejected file is just a part of the initial patch. At this point you have several solutions, the first is more simple : * make by hand the modification in file_a.rej to file_a and refresh the patch my_modification.patch * try to reorganize directly the patch my_modification.patch ('''DANGEROUS''') * use the Chris Mason's [[http://oss.oracle.com/~mason/mpatch/|mpatch]] to try to reorganize the patch (automatization of the preceding solution). In any case be wise with any modification ! |
| Line 308: | Line 489: |
| 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. |
Double check and update the description of the patch, using {{{hg qrefresh -e}}} and make sure to add the sage trac ticket number to the first line of the description. You may also rename the patch (using {{{sage -hg qrename}}}) by appending {{{trac_####}}} as a prefix. Then you should make sure that sage builds, runs, and passes tests, with just this patch applied on top of the 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. |
| Line 314: | Line 496: |
| 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 |
sage -hg export new_feature.patch > /path/to/new_feature.patch }}} Upload the file new_feature_for_trac.patch to the appropriate ticket on the Sage Trac server, creating the ticket if necessary. Generic procedures for using the trac system for Sage are described here: http://wiki.sagemath.org/TracGuidelines . Here are some further tips for Sage-Combinat tickets: * Keep the same patch name in the Sage-Combinat queue and on trac. * Assign it to milestone sage-combinat initially. Once it has a positive review it should be moved to the current merge milestone that is active. * Add "sage-combinat" to the CC field. That way ticket status changes show up at http://groups.google.com/group/sage-combinat-commits == Rebasing the patch queue on a new version of sage == This section is for maintainers of the patch queue. Idealy, switching to a new version of Sage should require no work. But sometimes some patches from the Sage community at large that were integrated in the new version of Sage may conflict with the Sage-Combinat patches. Here is how to rebase on them. In this example, we rebase from sage 3.4 to sage 3.4.1. This requires having access to vanilla sage/devel/sage-main directories for 3.4 and 3.4.1 which we assume to be respectively in {{{/opt/sage/devel/sage-main-3.4}}} and {{{/opt/sage/devel/sage-main}}} Start from a fresh sage-main from the previous sage version: {{{ cd /tmp hg clone /opt/sage/devel/sage-main-3.4 sage-main }}} Install the sage-combinat patches, and apply them all {{{ cd sage-main/.hg hg clone http://combinat.sagemath.org/patches patches cd .. hg qselect 3_4_1 hg qpush -a }}} Then we save the queue state, and launch a 3-way merge {{{ hg qsave -e -c hg pull /opt/sage/devel/sage-main hg update -C tip hg qselect -n hg qpush -m -a }}} |
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:
Contents
- Installation and basic usage
- Looking and selecting the patches
-
Creating and contributing patches
- Mercurial configuration
- Patch naming convention
- Patch description
- Creating a new patch (qnew)
- Editing the Sage sources
- Refreshing your patch (qrefresh)
- Removing a patch
- Pushing patches to the sage-combinat server
- In the case of Merging conflicts
- Handling rejection
- Exporting Patches for use with trac
- Rebasing the patch queue on a new version of sage
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
The instructions below assume that:
You need to have a very recent version of Sage already installed (say in /opt/sage) which can be started by typing sage at the command line
(it is recommended to use the most recent stable version, and in particular >= 4.3.1 as of 2010, march the 20)
The user has write access to the Sage installation tree
The user has access to: http://combinat.sagemath.org/patches/
With Sage < 4.7.1, if you do not already have an hg configuration file $HOME/.hgrc in your home directory, you need to create such a file containing the following (edit your name!!!):
[ui] username = Simon Cussonnet <Simon.Cussonnet at lycee-technique.thorel.eure.fr>
Notes:
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
1.2. Downloading and installing the Sage-combinat patches
sage -combinat install
1.2.1. Installing the Sage-combinat patches on OS X
There occurred several issues installing the Sage-combinat patches on OS X, which have to be solved BEFORE running sage -combinat install.
Have the [[http://developer.apple.com/technologies/tools/|developer
- tools (XCode)]] installed