Differences between revisions 2 and 34 (spanning 32 versions)
Revision 2 as of 2009-01-26 17:59:12
Size: 4444
Editor: slabbe
Comment:
Revision 34 as of 2009-01-26 22:38:27
Size: 5810
Editor: slabbe
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#pragma section-numbers on
Line 5: Line 3:
== Use sage-combinat patches == Here are the basics steps in order to use and contribute some of your code to sage-combinat. Note that a patch has a unique owner so you should only modify a patch that is already yours.
Line 7: Line 5:
=== Install sage-combinat === ~+1. Install sage-combinat+~
Line 9: Line 8:
   sage -combinat install $ sage -combinat install
Line 11: Line 10:
=== Moving around the patches ===
Line 13: Line 11:
The sage-combinat is a set of ordered patches. The behavior of moving around those is done like a stack: ~+2. Top, applied and unapplied patches+~

Sage-combinat is a stack of totally ordered patches. You may apply all of them, a part of them or none of them. To know which patch is the more recently applied patch:
Line 15: Line 15:
   hg qpop
   hg qpush
   hg qpop -a
   hg qpush -a
$ hg qtop # Displays the most recently applied patch
Line 20: Line 17:
To know which is actually on top or which patches are currently applied or unapplied: or which patches are currently applied or unapplied:
Line 22: Line 19:
   hg qapplied
   hg qunapplied
   hg qseries
   hg qtop
$ hg qapplied # Lists all patches in the queue which are currently applied
$ hg qunapplied # ------------------- " -------------------------- unapplied
Line 27: Line 22:
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: or all of them:
Line 29: Line 24:
   sage -b $ hg qseries
Line 31: Line 26:
Use
~+3. Applying and unapplying patches+~

The behavior of applying the patches is done like a stack. When a patch is applied, all the precedent ones are necessarily applied as well.
Line 33: Line 31:
   hg qdiff $ 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
Line 35: Line 36:
to display the actual modifications of the current top patch or use Note that after moving around the stack of patches, it is a good idea to rebuild sage before using it :
Line 37: Line 38:
   hg qstatus $ sage -b
$ sage
Line 39: Line 41:
to list simply the name of the affected files.
Line 41: Line 42:
== Contribute to sage-combinat == ~+4. Contents of patches+~
Line 43: Line 44:
Here are the basics steps in order to contribute some of your code to sage-combinat. 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. To display the content of the current top patch, use
{{{
$ hg qdiff # or
$ hg qstatus
}}}
whether to show a complete modifications or simply the name of the modified files.
Line 45: Line 51:
=== Create a patch where to put the changes === ~+5. Create a patch+~
Line 47: Line 53:
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: 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:
Line 49: Line 55:
    hg qnew my_improvement_AB.patch $ hg qpush -a                    #facultatif
$
hg qnew my_improvement_AB.patch
Line 51: Line 58:
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: 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.

~+6. 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. Use {{{qpop}}} and {{{qpush}}} to move to the desired patch to modify. Note that you can *not* use {{{qpop}}} and {{{qpush}}} commands once you started modifications.
Line 53: Line 64:
    hg qpush -a
    hg qnew my_improvement_AB.patch
$ hg qtop #to print the current top patch
$ hg qpop
$ hg qpush #to change the top patch currently applied
Line 56: Line 68:
It is suggested to add your initials (here AB) in the name so that everybody knows who owns what. 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>
}}}
Line 58: Line 78:
=== 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
}}}
Use
{{{
    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 ===
~+7. QRefresh the patch+~
Line 81: Line 82:
    hg qdiff
    hg qstatus
$ hg qdiff
$ hg qstatus
Line 86: Line 87:
    hg qrefresh $ hg qrefresh
Line 88: Line 89:
to put the actual modifications in the current top patch. You can make sure that it worked using the command to put the actual modifications in the current top patch. You can see that it worked when typing the command
Line 90: Line 91:
    hg qdiff
    hg qstatus
$ hg qdiff
$ hg qstatus
Line 93: Line 94:
again that should now display them. Moreover the command that should now include your modifications and by the command
Line 95: Line 96:
    hg diff
    hg status
$ hg diff
$ hg status
Line 98: Line 99:
should now display nothing. Note that you can now use qpop and qpush again since you don't actually have unfreshed modifications. that should not display them anymore.
Line 100: Line 101:
=== Do more modifications === ~+8. Do more modifications+~
Line 102: Line 103:
More modifications can be done to the same patch or to other patches you have already created. Follow again 1-3. After {{{qrefresh}}}, you can now use {{{qpop}}} and {{{qpush}}} again and modify the same or other patches you already created. See steps 3-7.
Line 104: Line 105:
=== Commit your changes to the local mercurial database === ~+9. Remove a patch+~
Line 106: Line 107:
After having done modifications to one or to many patches, you migth want to commit them to the local mercurial database: 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 :
Line 108: Line 109:
    hg qcommit $ hg qremove my_improvement_AB.patch
}}}
You may use
{{{
$ hg qseries
}}}
to confirm the patch is removed.


~+10. 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
Line 112: Line 126:
=== Merge your changes with other sage-combinat developpers === ~+11. Merge your changes with other sage-combinat developpers+~
Line 114: Line 128:
There is a possibility that somebody else pushed changes to the server since the last time you updated your sage-combinat tree. You will use the local mercurial database to merge those modifications. First pull any recent changes on the server by doing : There is a possibility that somebody else pushed changes to the server since the last time you updated your sage-combinat tree. The local mercurial database will be used to merge those modifications. First pull any recent changes on the server by doing :
Line 116: Line 130:
    cd .hg/patches
    hg pull -u
$ cd .hg/patches
$ hg pull -u
Line 121: Line 135:
    hg merge $ hg merge
Line 123: Line 137:
if there needed. if needed.
Line 125: Line 139:
TODO : write about conflicts... If there are conflicts between your changes and some recent changes on the server, then consult the [[http:/combinat/Mercurial|advanced instructions]].
Line 127: Line 141:
=== Push your changes to the server === ~+12. Push your changes to the server+~
Line 129: Line 143:
Here is where you must be prudent. Before committing any changes to the server, make sure that sage -br works fine: Here is where you must be prudent. Before committing any changes to the server, make sure that {{{sage -br}}} works fine:
Line 131: Line 145:
    hg qpop -a
    hg qpush -a
    sage -br
$ hg qpop -a
$ hg qpush -a
$ sage -br
Line 135: Line 149:
and that it passes the tests: and that it passes the tests
Line 137: Line 151:
    sage -t <filenames> $ sage -t <filenames>
Line 139: Line 153:
Then push your server after making sure again that there is no changes on the server: and maybe even that the notebook still works (!)
Line 141: Line 155:
    cd .hg/patches
    hg pull -u
    hg push
sage: notebook()
Line 145: Line 157:
Then push your changes to server after making sure one more time that there is no new changes on the server:
{{{
$ cd .hg/patches
$ hg pull -u
$ hg push
}}}

Use and Contribute to the sage-combinat tree : step by step

Here are the basics steps in order to use and contribute some of your code to sage-combinat. Note that a patch has a unique owner so you should only modify a patch that is already yours.

1. Install sage-combinat

$ sage -combinat install

2. Top, applied and unapplied patches

Sage-combinat is a stack of totally ordered patches. You may apply all of them, a part of them or none of them. To know which patch is the more recently applied patch:

$ hg qtop           # Displays the most recently applied patch

or which patches are currently applied or unapplied:

$ hg qapplied       # Lists all patches in the queue which are currently applied
$ hg qunapplied     #  ------------------- " --------------------------  unapplied

or all of them:

$ hg qseries 

3. Applying and unapplying patches

The behavior of applying the patches is done like a stack. When a patch is applied, all the precedent ones are necessarily applied as well.

$ 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

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

$ sage -b
$ sage

4. Contents of patches

To display the content of the current top patch, use

$ hg qdiff         # or
$ hg qstatus

whether to show a complete modifications or simply the name of the modified files.

5. Create a patch

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.

6. 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. Use qpop and qpush to move to the desired patch to modify. Note that you can *not* use qpop and qpush commands 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>

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

8. 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.

9. 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 the patch is removed.

10. 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.

11. Merge your changes with other sage-combinat developpers

There is a possibility that somebody else pushed changes to the server since the last time you updated your sage-combinat tree. The local mercurial database will be used to merge those modifications. First pull any recent changes on the server by doing :

$ cd .hg/patches
$ hg pull -u

and

$ hg merge

if needed.

If there are conflicts between your changes and some recent changes on the server, then consult the advanced instructions.

12. 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>

and maybe even that the notebook still works (!)

sage: notebook()

Then push your changes to server after making sure one more time that there is no new changes on the server:

$ cd .hg/patches
$ hg pull -u
$ hg push