Differences between revisions 33 and 35 (spanning 2 versions)
Revision 33 as of 2009-01-26 22:34:12
Size: 5802
Editor: slabbe
Comment:
Revision 35 as of 2009-01-28 02:08:34
Size: 6699
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
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. Here are the basics steps in order to contribute some of your code to sage-combinat.
We
assume that the sage-combinat patches are readilly installed (see above!!!!!!!!).
Line 5: Line 6:
~+1. Install sage-combinat+~
Line 7: Line 7:
== 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. Technically, they are managed as a Mercurial queue. Let's look at a typical stack of patches:
Line 8: Line 14:
$ sage -combinat install 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
Line 11: Line 28:
~+2. Top, applied and unapplied patches+~ 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).
Line 13: Line 33:
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: == Top, applied and unapplied patches ==

It is possible to move up and down the stack, applying all the patches up to a given one.
Line 15: Line 37:
$ 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
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 27: Line 43:
~+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.
If you get confused, the following can tell you which patches are applied or not:
Line 31: Line 45:
$ 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
hg qtop # Top applied patch
hg qapplied # Currently applied patches
hg qunapplied # Currently unapplied patches
Line 42: Line 50:
~+4. Contents of patches+~ Note that after moving around the stack of patches, it is necessary to rebuild sage before using it :
{{{
sage -b
sage
}}}
Line 44: Line 56:
To display the content of the current top patch, use == Looking inside patches ==

The content of the current top patch can be retrieved with
Line 46: Line 60:
$ hg qdiff # or
$ hg qstatus
hg qdiff
Line 49: Line 62:
whether to show a complete modifications or simply the name of the modified files. while a brief summary of the modifed files is given by
{{{
hg qstatus
}}}
Line 52: Line 68:

Note that a patch has a unique owner so you should only modify a patch that is already yours.
Line 157: Line 176:
Then push your changes to server after making sure again that there is no new changes on the server: Then push your changes to server after making sure one more time that there is no new changes on the server:

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

Here are the basics steps in order to contribute some of your code to sage-combinat. We assume that the sage-combinat patches are readilly installed (see above!!!!!!!!).

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

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

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

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