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