4414
Comment:

17022

Deletions are marked like this.  Additions are marked like this. 
Line 1:  Line 1: 
= Use and Contribute to the sagecombinat tree : step by step = == Use sagecombinat patches == === Install sagecombinat === {{{ sage combinat install }}} === Moving around the patches === The sagecombinat is a set of ordered patches. The behavior of moving around those is done like a stack: {{{ hg qpop hg qpush hg qpop a hg qpush a }}} To know which is actually on top or which patches are currently applied or unapplied: {{{ hg qapplied hg qunapplied hg qseries hg qtop }}} Important note : after moving around the stack of patches, and before using sage, don't forget to rebuild sage so that it corresonds to the current state of the stack: {{{ sage b }}} Use {{{ hg qdiff }}} to display the actual modifications of the current top patch or use {{{ hg qstatus }}} to list simply the name of the affected files. == Contribute to sagecombinat == Here are the basics steps in order to contribute some of your code to sagecombinat. Note that a patch has a unique owner. Never modify a patch that is not yours. If you already own a patch, you can go directly to paragraph 2. === Create a patch where to put the changes === Changes are always saved 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, first create a patch: {{{ hg qnew my_improvement_AB.patch }}} This creates a new patch right after the current top patch. Usually, a new patch is created on the top of the stack of patches and you can make sure of this by doing: {{{ hg qpush a hg qnew my_improvement_AB.patch }}} It is suggested to add your initials (here AB) in the name so that everybody knows who owns what. === Do your modifications === First, make sure the current top patch is the good one and that it is yours: {{{ hg qtop qnew my_improvement_AB.patch }}} Edit an or many existing files. Once you are done, you can review your modifications since the last qrefresh (explained below) or since the creation of the patch by doing: {{{ hg diff }}} 
#pragma sectionnumbers 2 = The SageCombinat patch server: step by step instructions = This page is meant as a stepbystep tutorial on using the SageCombinat patch server, from basic installation to contributing new patches: <<TableOfContents(3)>> 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. == Installation and basic usage == === Prerequisites === *WARNING*: The sagecombinat server is finaly being moved to its final official destination! ==== 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: * Sage 3.4 has just been released: http://sage.math.washington.edu/sage/src/index.html * Developpers should be using this server. * For simplicity, the server is currently configured with open readwrite access (no login/password required). Please do not abuse. ==== Old readonly 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/ ==== 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 lyceetechnique.torrez.eure.fr> [extensions] hgext.mq = extdiff = alias = [alias] qstatus = status rev 2:. [hooks] preqrefresh = (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 = hginterdiff }}} === Downloading and installing the Sagecombinat patches === {{{ sage combinat install }}} === Updating the SageCombinat patches === To update the SageCombinat 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 }}} === Uninstalling the Sagecombinat patches === {{{ sage b main }}} Now, you may destroy {{{.../sage/devel/sagecombinat/}}} (after checking that you do not have local changes!) == Looking and selecting the patches == === The Sagecombinat stack of patches === Sagecombinat 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: {{{ sage3.1.3.patch sage3.2.patch ... lazy_attributes4371nt.patch copy_on_write_fh.patch discrete_functionnt.patch crystals_alcove_path_model_bj.patch words_new_fcts_sl.patch }}} sage3.1.3 is at the bottom of the stack, and is applied first, while words_new_fcts_sl.patch is applied last. The patch sage3.2.patch contains all the sagecombinat patches that have readilly been integrated in sage 3.2 (see "using sagecombinat with older versions of sage"). The patch lazy_attributes4371nt.patch is about lazy attributes, related to [[http://sagetrac.org/sage_trac/ticket/4371 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. === 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 }}} === Looking inside patches === The content of the current top patch can be retrieved with: {{{ sage hg qdiff }}} while the files modified in the top patch can be seen with: {{{ sage hg qstatus }}} Warning: {{{ sage hg qstatus }}} will return irrelevant information if there is no patch currently on top of the stack. Tip: use {{{ hg export bla.patch }}} or just open the patch to get extra information like the description of the patch. === Using the sagecombinat patches with an older version of sage === For the convenience of the user, it is usually possible to use the sagecombinat 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 {{{sage3.0.2.patch}}}. This particular patch contains all the sagecombinat 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 }}} === 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 }}} == Creating and contributing patches == === 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: {{{ rootsystemslattices_nt.patch partitions_fix_3244_mh.patch crystalsaffine_as.patch freemodules_1_mh.patch freemodules_2_mh.patch freemodules_final.patch dyckwords_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. === Patch description === Each patch starts with a description header. This is the first thing that will be seen by someone opening the patch. Also this description is preserved upon hg export, and will end up into the history of Sage. So it should be as meaningful as possible. Typically, this description will match with the summary + description of the (upcoming) trac ticket. 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: {{{ 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. === 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 m "description of the patch" }}} where ab are your initials. 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 "description of the patch" }}} will create the new patch including the current 'orphaned' changes into it. === 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/sagecombinat/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> }}} === Refreshing your patch (qrefresh) === Currently, the modifications are still not part of the patch as may be seen with the commands {{{ 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}}}). 
Line 69:  Line 289: 
hg status }}} to list simply the modified files. Note that you can't use qpop and qpush commands once you started modifications. If you added a file, you must specify it by the command: {{{ hg add <filename> }}} === QRefresh the patch === 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 make sure that it worked using the command {{{ hg qdiff hg qstatus }}} again that should now display them. Moreover the command {{{ hg diff hg status }}} should now display nothing. Note that you can now use qpop and qpush again since you don't actually have unfreshed modifications. === Do more modifications === More modifications can be done to the same patch or to other patches you have already created. Follow again 13. === Commit your changes to the local mercurial database === After having done modifications to one or to many patches, you migth want to commit them to the local mercurial database: {{{ hg qcommit }}} It includes all the changes to the patches done since the last commit. An editor will appear for you to provide a description of all the changes you made. === Merge your changes with other sagecombinat developpers === There is a possibility that somebody else pushed changes to the server since the last time you updated your sagecombinat tree. You will use the local mercurial database to merge those modifications. First pull any recent changes on the server by doing : {{{ cd .hg/patches hg pull u }}} and {{{ hg merge }}} if there needed. TODO : write about conflicts... === Push your changes to the server === Here is where you must be prudent. Before committing any changes to the server, make sure that sage br works fine: {{{ hg qpop a hg qpush a sage br }}} and that it passes the tests: {{{ sage t <filenames> }}} Then push your server after making sure again that there is no changes on the server: {{{ cd .hg/patches hg pull u hg push }}} 
sage hg qrefresh }}} to put the actual modifications in the current top patch. Tip: on a regular basis, use instead: {{{ sage hg qrefresh e }}} 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. You can check that the modifications have been included in the patch with: {{{ sage hg qdiff sage hg qstatus }}} Also, they should not 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. === 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. === Pushing patches to the sagecombinat server === Go to the sagecombinat directory, and make sure that there is no local changes: {{{ cd $SAGE_ROOT/devel/sagecombinat sage hg status }}} Otherwise discard 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/sagecombinat/.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! === 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. Double check and update the description of the patch, using {{{hg qrefresh e}}}. 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. {{{ cd $SAGE_ROOT/devel/sagecombinat 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 SageCombinat tickets: * Keep the same patch name in the SageCombinat queue and on trac. * Assign it to milestone sagecombinat initially. Once it has a positive review it should be moved to the current merge milestone that is active. * Add "sagecombinat" to the CC field. That way ticket status changes show up at http://groups.google.com/group/sagecombinatcommits 
The SageCombinat patch server: step by step instructions
This page is meant as a stepbystep tutorial on using the SageCombinat patch server, from basic installation to contributing new patches:
Contents
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 sagecombinat 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:
Sage 3.4 has just been released: http://sage.math.washington.edu/sage/src/index.html
 Developpers should be using this server.
 For simplicity, the server is currently configured with open readwrite access (no login/password required). Please do not abuse.
1.1.2. Old readonly 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 lyceetechnique.torrez.eure.fr> [extensions] hgext.mq = extdiff = alias = [alias] qstatus = status rev 2:. [hooks] preqrefresh = (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 = hginterdiff
1.2. Downloading and installing the Sagecombinat patches
sage combinat install
1.3. Updating the SageCombinat patches
To update the SageCombinat 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 Sagecombinat patches
sage b main
Now, you may destroy .../sage/devel/sagecombinat/ (after checking that you do not have local changes!)
2. Looking and selecting the patches
2.1. The Sagecombinat stack of patches
Sagecombinat 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:
sage3.1.3.patch sage3.2.patch ... lazy_attributes4371nt.patch copy_on_write_fh.patch discrete_functionnt.patch crystals_alcove_path_model_bj.patch words_new_fcts_sl.patch
sage3.1.3 is at the bottom of the stack, and is applied first, while words_new_fcts_sl.patch is applied last. The patch sage3.2.patch contains all the sagecombinat patches that have readilly been integrated in sage 3.2 (see "using sagecombinat with older versions of sage"). The patch lazy_attributes4371nt.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 the files modified in the top patch can be seen with:
sage hg qstatus
Warning: sage hg qstatus will return irrelevant information if there is no patch currently on top of the stack.
Tip: use
hg export bla.patch
or just open the patch to get extra information like the description of the patch.
2.4. Using the sagecombinat patches with an older version of sage
For the convenience of the user, it is usually possible to use the sagecombinat 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 sage3.0.2.patch. This particular patch contains all the sagecombinat 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:
rootsystemslattices_nt.patch partitions_fix_3244_mh.patch crystalsaffine_as.patch freemodules_1_mh.patch freemodules_2_mh.patch freemodules_final.patch dyckwords_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. Patch description
Each patch starts with a description header. This is the first thing that will be seen by someone opening the patch. Also this description is preserved upon hg export, and will end up into the history of Sage. So it should be as meaningful as possible.
Typically, this description will match with the summary + description of the (upcoming) trac ticket. 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:
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.
3.3. 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 m "description of the patch"
where ab are your initials. 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 "description of the patch"
will create the new patch including the current 'orphaned' changes into it.
3.4. 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/sagecombinat/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.5. Refreshing your patch (qrefresh)
Currently, the modifications are still not part of the patch as may be seen with the commands
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 instead:
sage hg qrefresh e
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.
You can check that the modifications have been included in the patch with:
sage hg qdiff sage hg qstatus
Also, they should not 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.6. 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.7. Pushing patches to the sagecombinat server
Go to the sagecombinat directory, and make sure that there is no local changes:
cd $SAGE_ROOT/devel/sagecombinat sage hg status
Otherwise discard 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/sagecombinat/.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.8. 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.
Double check and update the description of the patch, using hg qrefresh e.
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.
cd $SAGE_ROOT/devel/sagecombinat 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 SageCombinat tickets:
 Keep the same patch name in the SageCombinat queue and on trac.
 Assign it to milestone sagecombinat initially. Once it has a positive review it should be moved to the current merge milestone that is active.
Add "sagecombinat" to the CC field. That way ticket status changes show up at http://groups.google.com/group/sagecombinatcommits