[PATCH 1 of 1] docs/overview.txt: Provide short mercurial HOWTO

[Titus von Boxberg <titus at v9g dot de>]

# HG changeset patch
# User Titus von Boxberg <titus@v9g.de>
# Date 1274449425 -7200
# Node ID 15c9bd7328f0310785ee8e3c581971ef173178b1
# Parent  0a59fff8643bc15036135d081deb087cef53fde2
docs/overview.txt: Provide short mercurial HOWTO

The usage of hg mq is imho not very well documented.
Give a short intro for the most important use cases
for contributions to ct-ng.

diff -r 0a59fff8643b -r 15c9bd7328f0 docs/overview.txt
--- a/docs/overview.txt	Mon May 17 14:11:08 2010 +0200
+++ b/docs/overview.txt	Fri May 21 15:43:45 2010 +0200
@@ -689,10 +689,168 @@
 The SoB line is clearly described in Documentation/SubmittingPatches , section
 12, of your favourite Linux kernel source tree.
 
-Then you'll need to correctly configure Mercurial. There are two extensions
-that you may find usefull:
-  - mq        : http://mercurial.selenic.com/wiki/MqExtension
-  - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
+
+How to Use Mercurial |
+---------------------+
+
+For larger or more frequent contributions, mercurial should be used.
+
+PREREQUISITES:
+
+Configuring Mercurial:
+  You need mercurial with the following extensions:
+   - mq        : http://mercurial.selenic.com/wiki/MqExtension
+   - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
+  Usually these are already part of the installation package.
+  The mq extension maintains a separate queue of your local changes
+  that you can change at any later time.
+  With the patchbomb extension you can email those patches directly
+  from your local repo.
+
+  Your configuration file for mercurial, e.g. ~/.hgrc should contain
+  at least the following sections (but have a look at `man hgrc`):
+  # ---
+  [email]
+  # configure sending patches directly via Mercurial
+  from = "Your Name" <your@email.address>
+  # How to send email:
+  method = smtp 
+
+  [smtp]
+  # SMTP configuration (only for method=smtp)
+  host = localhost
+  tls = true
+  username =
+  password =
+
+  [extensions]
+  # The following lines enable the two extensions:
+  hgext.mq =
+  hgext.patchbomb =
+  # ----
+
+Create your local repository as a clone:
+  hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
+
+Setting up the mq extension in your local copy:
+  cd crosstool-ng
+  hg qinit
+
+
+CREATING PATCHES:
+
+Recording your changes in the patch queue maintained by mq:
+  # First, create a new patch entry in the patch queue:
+  hg qnew -D -U -e short_patch_name1
+  <edit patch description as commit message (see below for an example)>
+
+  <now edit the ct-ng sources and check them>
+
+  # if you execute `hg status` here, your modifications of the working
+  # copy should show up.
+  
+  # Now the following command takes your modifications from the working copy 
+  # into the patch entry
+  hg qrefresh -D [-e]
+  <reedit patch description [-e] if desired>
+
+  # Now your changes are recorded, and `hg status` should show a clean working copy
+
+Repeat the above step for all your modifications.
+The command `hg qseries` informs you about the content of your patch queue.
+
+
+CONTRIBUTING YOUR PATCHES:
+
+The command hg email sends your patches as emails.
+The flag --outgoing selects all patches that are not yet
+put into the upstream repository.
+These emails get the subject
+[PATCH x of <your patch queue length>] <your short patch #x description>.
+In addition, it lets you prepare a first introductory email where you can
+extend the default subject [PATCH 0 of <your patch queue length>]
+and prepare a message body where you should describe the scope of
+and motivation for the patches.
+Note: replace " (at) " with "@"
+
+  hg email --outgoing --intro   \
+           --from '"Your Full NAME" <your.email (at) your.domain>'   \
+           --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
+           --cc 'crossgcc (at) sourceware.org'
+
+Use hg email with the additional command line switch -n to
+first have a look at the emails without actually sending them.
+
+
+MAINTAINING YOUR PATCHES:
+
+When the patches are refined by discussing them on the mailing list,
+you may want to finalize and resend them.
+
+The mq extension has the idiosyncrasy of imposing a stack onto the queue:
+You can always reedit/refresh only the patch on top of stack.
+The queue consists of applied and unapplied patches
+(if you reached here via the above steps, all of your patches are applied),
+where the 'stack' consists of the applied patches, and 'top of stack'
+is the latest applied patch.
+
+The following output of `hg qseries` is now used as an example:
+  0 A short_patch_name1
+  1 A short_patch_name2
+  2 A short_patch_name3
+  3 A short_patch_name4
+
+You are now able to edit patch 'short_patch_name4':
+  <Edit the sources>
+  # and execute again
+  hg qrefresh -D [-e]
+  <and optionally [-e] reedit the commit message>
+
+If you want to edit e.g. patch short_patch_name2, you have to modify
+mq's stack so this patch gets top of stack.
+For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
+
+  hg qgoto short_patch_name2
+  # The patch queue should now look like
+  hg qseries
+    0 A short_patch_name1
+    1 A short_patch_name2
+    2 U short_patch_name3
+    3 U short_patch_name4
+  # so patch # 1 (short_patch_name2) is top of stack.
+  <now reedit the sources for short_patch_name2>
+  # and execute again
+  hg qrefresh -D [-e]
+  <and optionally [-e] reedit the commit message>
+  # the following command reapplies the now unapplied two patches:
+  hg qpush -a
+  # you can also use `hg qgoto short_patch_name4` to get there again.
+
+
+RESENDING YOUR REEDITED PATCH:
+
+Now you may want to contribute your edited patch short_patch_name2.
+The command hg email lets you send a particular patch with the 
+command line argument -r <revision>.
+BEWARE: This <revision> is NOT the patch number in your queue,
+it is the changeset number of your repository.
+  # Thus, you have to find out the repository revision first:
+  hg log | more
+  # shows something like
+    ...
+    changeset:    <revision>:<id>
+    tag:          short_patch_name2
+    ...
+
+The <revision> after "changeset:" is the one hg email expects for the -r command line argument.
+  # So, the following command resends that revision:
+  hg email -r <revision> \
+     --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>' \
+     --cc 'crossgcc (at) sourceware.org'
+  # again, you can use -n first to make sure everything is ok with that email.
+
+
+HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
 
 Commit messages should look like (without leading pipes):
  |component: short, one-line description
@@ -707,31 +865,6 @@
  |For any later versions, the directory name does have the version, such as
  |cloog-ppl-0.15.4.
 
-Here's a typical hacking session:
-  hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
-  cd crosstool-ng
-  hg qinit
-  hg qnew -D -U -e my_first_patch
-  *edit patch description*
-  *hack* *hack* *check* *fails* *hack* *hack* *check* *works*
-  hg qref -D -e
-  *edit patch description, serving as commit message*
-  hg qnew -D -U -e my_second_patch
-  *edit patch description*
-  *hack* *hack* *check* *fails* *hack* *hack* *check* *works*
-  hg qref -D -e
-  *edit patch description, serving as commit message*
-  hg email --outgoing --intro   \
-           --from '"Your Full NAME" <your.email (at) your.domain>'   \
-           --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
-           --cc 'crossgcc (at) sourceware.org'
-  *edit introductory message*
-  *wait for feedback*
-  *re-send if no answer for a few days*
-
-Note: replace '(at)' above with a plain '@'.
-
-
 _____________
             /
 Internals  /

--
For unsubscribe information see http://sourceware.org/lists.html#faq