Differences between revisions 2 and 18 (spanning 16 versions)

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. Familiarize with moving around the patches

The sage-combinat 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 patch is currently on top of the stack :

   hg qtop

or which patches are currently applied or unapplied:

   hg qapplied
   hg qunapplied

or all of them:

   hg qseries

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

   sage -b

To display the content of the current top patch, use

   hg qdiff         # or
   hg qstatus

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

3. Create a patch

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, 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 current top 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.

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

    hg qtop

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

    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>

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

6. Do more modifications

You can now use qpop and qpush again and modify other patches you already created. Then follow again 2-5.

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

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

TODO : write about conflicts...

9. 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 new changes on the server:

    cd .hg/patches
    hg pull -u
    hg push

-  ⇤ ← Revision 2 as of 2009-01-26 17:59:12 → 
  Size: 4444
  Editor: slabbe
  Comment:
+   ← Revision 18 as of 2009-01-26 19:01:25 → ⇥
  Size: 4281
  Editor: slabbe
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 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 11:
+Line 10:
-=== Moving around the patches ===
+~+2. Familiarize with moving around the patches+~
 Line 20:
-To know which is actually on top or which patches are currently applied or unapplied:
+To know which patch is currently on top of the stack :
{{{
   hg qtop
}}}
or which patches are currently applied or unapplied:
-Line 24:
+Line 28:
+}}}
or all of them:
{{{
-Line 25:
+Line 32:
-   hg qtop
-Line 27:
+Line 33:
-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:
+Note that after moving around the stack of patches, it is a good idea to rebuild sage before using it :
-Line 31:
+Line 37:
-Use
+To display the content of the current top patch, use
-Line 33:
+Line 39:
-   hg qdiff
}}}
to display the actual modifications of the current top patch or use
{{{
+   hg qdiff         # or
-Line 39:
+Line 42:
-to list simply the name of the affected files.
+whether to show a complete diff or simply the name of the modified files.
-Line 41:
+Line 44:
-== Contribute to sage-combinat ==
+~+3. Create a patch+~
-Line 43:
+Line 46:
-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.

=== 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:
+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, start by creating a patch:
-Line 49:
+Line 48:
+    hg qpush -a                      #facultatif
 Line 51:
-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.
+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 current top 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.
-Line 58:
+Line 53:
-=== Do your modifications ===
+~+4. Do your modifications+~
-Line 60:
+Line 55:
-First, make sure the current top patch is the good one and that it is yours:
+Before making any modifications, make sure the current top patch is yours and is the one you want to add your modifications.
-Line 63:
+Line 58:
-    qnew my_improvement_AB.patch
-Line 65:
+Line 59:
-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:
+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:
-Line 69:
+Line 63:
-Use
+or
-Line 77:
+Line 71:
-=== QRefresh the patch ===
+~+5. QRefresh the patch+~
-Line 88:
+Line 83:
-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 93:
+Line 88:
-again that should now display them. Moreover the command
+that should now include your modifications and by the command
-Line 98:
+Line 93:
-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 95:
-=== Do more modifications ===
+~+6. Do more modifications+~
-Line 102:
+Line 97:
-More modifications can be done to the same patch or to other patches you have already created. Follow again 1-3.
+You can now use qpop and qpush again and modify other patches you already created. Then follow again 2-5.
-Line 104:
+Line 99:
-=== Commit your changes to the local mercurial database ===
+~+7. Commit your changes to the local mercurial database+~
-Line 112:
+Line 107:
-=== Merge your changes with other sage-combinat developpers ===
+~+8. Merge your changes with other sage-combinat developpers+~
-Line 114:
+Line 109:
-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 123:
+Line 118:
-if there needed.
+if needed.
-Line 127:
+Line 122:
-=== Push your changes to the server ===
+~+9. Push your changes to the server+~
-Line 139:
+Line 134:
-Then push your server after making sure again that there is no changes on the server:
+Then push your server after making sure again that there is no new changes on the server:

Diff for "combinat/MercurialStepByStep"

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