1.1 --- a/docs/overview.txt Mon May 17 14:11:08 2010 +0200
1.2 +++ b/docs/overview.txt Sat May 22 18:48:50 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 /