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