docs/overview.txt
changeset 2069 366bd2b22675
parent 1937 384b7f8fc780
     1.1 --- a/docs/overview.txt	Wed Apr 28 22:24:01 2010 +0200
     1.2 +++ b/docs/overview.txt	Thu Aug 05 17:59:51 2010 +0200
     1.3 @@ -689,10 +689,189 @@
     1.4  The SoB line is clearly described in Documentation/SubmittingPatches , section
     1.5  12, of your favourite Linux kernel source tree.
     1.6  
     1.7 -Then you'll need to correctly configure Mercurial. There are two extensions
     1.8 -that you may find usefull:
     1.9 -  - mq        : http://mercurial.selenic.com/wiki/MqExtension
    1.10 -  - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
    1.11 +
    1.12 +How to Use Mercurial |
    1.13 +---------------------+
    1.14 +
    1.15 +For larger or more frequent contributions, mercurial should be used.
    1.16 +
    1.17 +PREREQUISITES:
    1.18 +
    1.19 +Configuring Mercurial:
    1.20 +  You need mercurial with the following extensions:
    1.21 +   - mq        : http://mercurial.selenic.com/wiki/MqExtension
    1.22 +   - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
    1.23 +  Usually, these two extensions are already part of the installation package.
    1.24 +  The mq extension maintains a separate queue of your local changes
    1.25 +  that you can change at any later time.
    1.26 +  With the patchbomb extension you can email those patches directly
    1.27 +  from your local repo.
    1.28 +
    1.29 +  Your configuration file for mercurial, e.g. ~/.hgrc should contain
    1.30 +  at least the following sections (but have a look at `man hgrc`):
    1.31 +  # ---
    1.32 +  [email]
    1.33 +  # configure sending patches directly via Mercurial
    1.34 +  from = "Your Name" <your@email.address>
    1.35 +  # How to send email:
    1.36 +  method = smtp
    1.37 +
    1.38 +  [smtp]
    1.39 +  # SMTP configuration (only for method=smtp)
    1.40 +  host = localhost
    1.41 +  tls = true
    1.42 +  username =
    1.43 +  password =
    1.44 +
    1.45 +  [extensions]
    1.46 +  # The following lines enable the two extensions:
    1.47 +  hgext.mq =
    1.48 +  hgext.patchbomb =
    1.49 +  # ----
    1.50 +
    1.51 +Create your local repository as a clone:
    1.52 +  hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
    1.53 +
    1.54 +Setting up the mq extension in your local copy:
    1.55 +  cd crosstool-ng
    1.56 +  hg qinit
    1.57 +
    1.58 +
    1.59 +CREATING PATCHES:
    1.60 +
    1.61 +Recording your changes in the patch queue maintained by mq:
    1.62 +  # First, create a new patch entry in the patch queue:
    1.63 +  hg qnew -D -U -e short_patch_name1
    1.64 +  <edit patch description as commit message (see below for an example)>
    1.65 +
    1.66 +  <now edit the ct-ng sources and check them>
    1.67 +
    1.68 +  # if you execute `hg status` here, your modifications of the working
    1.69 +  # copy should show up.
    1.70 +
    1.71 +  # Now the following command takes your modifications from the working copy
    1.72 +  # into the patch entry
    1.73 +  hg qrefresh -D [-e]
    1.74 +  <reedit patch description [-e] if desired>
    1.75 +
    1.76 +  # Now your changes are recorded, and `hg status` should show a clean
    1.77 +  # working copy
    1.78 +
    1.79 +Repeat the above steps for all your modifications.
    1.80 +The command `hg qseries` informs you about the content of your patch queue.
    1.81 +
    1.82 +
    1.83 +CONTRIBUTING YOUR PATCHES:
    1.84 +
    1.85 +Once you are satisfied with your patch series, you can (you should!)
    1.86 +contribute them back to upstream.
    1.87 +This is easily done using the `hg email` command.
    1.88 +
    1.89 +`hg email` sends your new changesets to a specified list of recipients,
    1.90 +each patch in its own email, all ordered in the way you entered them (oldest
    1.91 +first). The command line flag --outgoing selects all changesets that are in
    1.92 +your local but not yet in the upstream repository. Here, these are exactly
    1.93 +the ones you entered into your local patch queue in the section above, so
    1.94 +--outgoing is what you want.
    1.95 +
    1.96 +Each email gets the subject set to:  "[PATCH x of n] <series summary>"
    1.97 +where 'x' is the serial number in the email series, and 'n' is the total number
    1.98 +of patches in the series. The body of the email is the complete patch, plus
    1.99 +a handful of metadata, that helps properly apply the patch, keeping the log
   1.100 +message, attribution and date, tracking file changes (move, delete, modes...)
   1.101 +
   1.102 +`hg email` also threads all outgoing patch emails below an introductory
   1.103 +message. You should use the introductory message (command line flag --intro)
   1.104 +to describe the scope and motivation for the whole patch series. The subject
   1.105 +for the introductory message gets set to:  "[PATCH 0 of n] <series summary>"
   1.106 +and you get the chance to set the <series summary>.
   1.107 +
   1.108 +Here is a sample `hg email` complete command line:
   1.109 +Note: replace " (at) " with "@"
   1.110 +
   1.111 +  hg email --outgoing --intro   \
   1.112 +           --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
   1.113 +           --cc 'crossgcc (at) sourceware.org'
   1.114 +
   1.115 +  # It then opens an editor and lets you enter the subject
   1.116 +  # and the body for the introductory message.
   1.117 +
   1.118 +Use `hg email` with the additional command line switch -n to
   1.119 +first have a look at the email(s) without actually sending them.
   1.120 +
   1.121 +
   1.122 +MAINTAINING YOUR PATCHES:
   1.123 +
   1.124 +When the patches are refined by discussing them on the mailing list,
   1.125 +you may want to finalize and resend them.
   1.126 +
   1.127 +The mq extension has the idiosyncrasy of imposing a stack onto the queue:
   1.128 +You can always reedit/refresh only the patch on top of stack.
   1.129 +The queue consists of applied and unapplied patches
   1.130 +(if you reached here via the above steps, all of your patches are applied),
   1.131 +where the 'stack' consists of the applied patches, and 'top of stack'
   1.132 +is the latest applied patch.
   1.133 +
   1.134 +The following output of `hg qseries` is now used as an example:
   1.135 +  0 A short_patch_name1
   1.136 +  1 A short_patch_name2
   1.137 +  2 A short_patch_name3
   1.138 +  3 A short_patch_name4
   1.139 +
   1.140 +You are now able to edit patch 'short_patch_name4' (which is top of stack):
   1.141 +  <Edit the sources>
   1.142 +  # and execute again
   1.143 +  hg qrefresh -D [-e]
   1.144 +  <and optionally [-e] reedit the commit message>
   1.145 +
   1.146 +If you want to edit e.g. patch short_patch_name2, you have to modify
   1.147 +mq's stack so this patch gets top of stack.
   1.148 +For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
   1.149 +
   1.150 +  hg qgoto short_patch_name2
   1.151 +  # The patch queue should now look like
   1.152 +  hg qseries
   1.153 +    0 A short_patch_name1
   1.154 +    1 A short_patch_name2
   1.155 +    2 U short_patch_name3
   1.156 +    3 U short_patch_name4
   1.157 +  # so patch # 1 (short_patch_name2) is top of stack.
   1.158 +  <now reedit the sources for short_patch_name2>
   1.159 +  # and execute again
   1.160 +  hg qrefresh -D [-e]
   1.161 +  <and optionally [-e] reedit the commit message>
   1.162 +  # the following command reapplies the now unapplied two patches:
   1.163 +  hg qpush -a
   1.164 +  # you can also use `hg qgoto short_patch_name4` to get there again.
   1.165 +
   1.166 +
   1.167 +RESENDING YOUR REEDITED PATCHES:
   1.168 +
   1.169 +By mailing list policy, please resend your complete patch series.
   1.170 +--> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
   1.171 +
   1.172 +
   1.173 +SYNCING WITH UPSTREAM AGAIN:
   1.174 +
   1.175 +You can sync your repo with upstream at any time by executing
   1.176 +  # first unapply all your patches:
   1.177 +  hg qpop -a
   1.178 +  # next fetch new changesets from upstream
   1.179 +  hg pull
   1.180 +  # then update your working copy
   1.181 +  hg up
   1.182 +  # optionally remove already upstream integrated patches (see below)
   1.183 +  hg qdelete <short_name_of_already_applied_patch>
   1.184 +  # and reapply your patches if any non upstream-integrated left (but see below)
   1.185 +  hg qpush -a
   1.186 +
   1.187 +Eventually, your patches get included into the upstream repository
   1.188 +which you initially cloned.
   1.189 +In this case, before executing the hg qpush -a from above
   1.190 +you should manually "hg qdelete" the patches that are already integrated upstream.
   1.191 +
   1.192 +
   1.193 +HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
   1.194  
   1.195  Commit messages should look like (without leading pipes):
   1.196   |component: short, one-line description
   1.197 @@ -707,31 +886,6 @@
   1.198   |For any later versions, the directory name does have the version, such as
   1.199   |cloog-ppl-0.15.4.
   1.200  
   1.201 -Here's a typical hacking session:
   1.202 -  hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
   1.203 -  cd crosstool-ng
   1.204 -  hg qinit
   1.205 -  hg qnew -D -U -e my_first_patch
   1.206 -  *edit patch description*
   1.207 -  *hack* *hack* *check* *fails* *hack* *hack* *check* *works*
   1.208 -  hg qref -D -e
   1.209 -  *edit patch description, serving as commit message*
   1.210 -  hg qnew -D -U -e my_second_patch
   1.211 -  *edit patch description*
   1.212 -  *hack* *hack* *check* *fails* *hack* *hack* *check* *works*
   1.213 -  hg qref -D -e
   1.214 -  *edit patch description, serving as commit message*
   1.215 -  hg email --outgoing --intro   \
   1.216 -           --from '"Your Full NAME" <your.email (at) your.domain>'   \
   1.217 -           --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
   1.218 -           --cc 'crossgcc (at) sourceware.org'
   1.219 -  *edit introductory message*
   1.220 -  *wait for feedback*
   1.221 -  *re-send if no answer for a few days*
   1.222 -
   1.223 -Note: replace '(at)' above with a plain '@'.
   1.224 -
   1.225 -
   1.226  _____________
   1.227              /
   1.228  Internals  /