Re: minor correction in container.txi, first contribution

[Thorsten Meyer]

Jaroslav Hajek wrote:
> Instead of repeatedly doing rollback/commit, you may want to get
> familiar with mercurial queues. A simplified sequence is:
> 
> hg qnew my-first-patch
> ... edit sources ...
> hg qref
> ... edit more ...
> hg qref
> ... even more ...
> hg export -o ../my_first_patch.diff qtip
> ... send patch to mailing list
Thanks for the advice

> perhaps we could add this to the contrib.txi guide...
Here is a changeset where I added a second example using mercurial
queues and slightly changed the introduction text.

A question regarding formatting of examples:
Is there a rule for the maximum line length of examples? If not I
would suggest introducing one that makes sure that an example line
fits on one line in all of the pdf and ps documents.

regards

Thorsten


# HG changeset patch
# User Thorsten Meyer <address@hidden>
# Date 1223068209 -7200
# Node ID 93b7ef7e29ca6bfbaf44fead7ce0605c9b3c86af
# Parent  397c021e120568cb005fd2e68e76f9c826ea281c
help new contributors with mercurial

diff -r 397c021e1205 -r 93b7ef7e29ca doc/ChangeLog
--- a/doc/ChangeLog     Fri Oct 03 14:05:22 2008 +0200
+++ b/doc/ChangeLog     Fri Oct 03 23:10:09 2008 +0200
@@ -1,3 +1,6 @@
+2008-10-03  Thorsten Meyer <address@hidden>
+        * interpreter/contrib.txi: added example for mercurial queues
+        
 2008-10-03  Thorsten Meyer <address@hidden>
         * interpreter/contrib.txi: correction of the mercurial example
         
diff -r 397c021e1205 -r 93b7ef7e29ca doc/interpreter/contrib.txi
--- a/doc/interpreter/contrib.txi       Fri Oct 03 14:05:22 2008 +0200
+++ b/doc/interpreter/contrib.txi       Fri Oct 03 23:10:09 2008 +0200
@@ -42,20 +42,60 @@
 
 The preferable form of contribution is creating a Mercurial changeset and
 sending it via e-mail to the octave-maintainers mailing list. Mercurial is the
-SCM system currently used to develop Octave. Other forms of contributions (e.g.
-simple diff patches) are also acceptable, but they slow down the review 
process.
-If you want to make more contributions, you should really get familiar with
-Mercurial.  A good place to start is 
address@hidden://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}.
-A simplified contribution sequence could look like this:
+source code management system currently used to develop Octave. Other forms of 
+contributions (e.g. simple diff patches) are also acceptable, but they slow 
+down the review process. If you want to make more contributions, you should 
+really get familiar with Mercurial.  A good place to start is 
address@hidden://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}. There you 
will
+also find help how to install Mercurial.
 
+A simple contribution sequence could look like this:
 @example
 hg clone http://www.octave.org/hg/octave
+                             # make a local copy of the octave 
+                             # source repository
 cd octave
 # change some sources...
 hg commit -m "make Octave the coolest software ever"
+                             # commit the changeset into your
+                             # local repository
 hg export -o ../cool.diff tip
+                             # export the changeset to a diff
+                             # file
 # send ../cool.diff via email
address@hidden example
+
+You may want to get familiar with Mercurial queues to manage your changesets.
+Here is a slightly less simple example using Mercurial queues, where you work 
+on two unrelated changesets in parallel and update one of the changesets after 
+discussion in the maintainers mailing list:
address@hidden
+hg qnew nasty_bug            # create a new patch 
+# change sources...
+hg qref                      # save the changes into the patch
+# change even more...
+hg qref -m "solution to nasty bug!"
+                             # save again with commit message
+hg export -o ../nasty.diff tip
+                             # export the patch
+# send ../nasty.diff via email
+hg qpop                      # undo the application of the patch
+                             # and remove the changes from the
+                             # source tree
+hg qnew doc_improvements     # create an unrelated patch 
+# change doc sources...
+hg qref -m "could not find myfav.m in the doc"
+                             # save the changes into the patch
+hg export -o ../doc.diff tip
+                             # export the second patch
+# send ../doc.diff tip via email
+hg qpop
+# discussion in the maintainers mailing list ...
+hg gpush nasty_bug           # apply the patch again
+# change sources yet again ...
+hg qref
+hg export -o ../nasty2.diff tip
+# send ../nasty2.diff via email
 @end example
 
 @node General Guidelines