yann@2076: File.........: 7 - Contributing to crosstool-NG.txt yann@2076: Copyrigth....: (C) 2010 Yann E. MORIN yann@2076: License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5 yann@2076: yann@2076: yann@2076: Contributing to crosstool-NG / yann@2076: _____________________________/ yann@2076: yann@2076: yann@2076: Sending a bug report | yann@2076: ---------------------+ yann@2076: yann@2076: If you need to send a bug report, please send a mail with subject yann@2076: prefixed with "[CT_NG]" with to following destinations: yann@2076: TO: yann.morin.1998 (at) anciens.enib.fr yann@2076: CC: crossgcc (at) sourceware.org yann@2076: yann@2076: yann@2076: Sending patches | yann@2076: ----------------+ yann@2076: yann@2076: If you want to enhance crosstool-NG, there's a to-do list in the TODO file. yann@2076: yann@2076: Patches should come with the appropriate SoB line. A SoB line is typically yann@2076: something like: yann@2076: Signed-off-by: John DOE yann@2076: yann@2076: The SoB line is clearly described in Documentation/SubmittingPatches , section yann@2076: 12, of your favourite Linux kernel source tree. yann@2076: yann@2076: yann@2076: How to Use Mercurial | yann@2076: ---------------------+ yann@2076: yann@2076: For larger or more frequent contributions, mercurial should be used. yann@2076: yann@2076: PREREQUISITES: yann@2076: yann@2076: Configuring Mercurial: yann@2076: You need mercurial with the following extensions: yann@2076: - mq : http://mercurial.selenic.com/wiki/MqExtension yann@2076: - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension yann@2076: Usually, these two extensions are already part of the installation package. yann@2076: The mq extension maintains a separate queue of your local changes yann@2076: that you can change at any later time. yann@2076: With the patchbomb extension you can email those patches directly yann@2076: from your local repo. yann@2076: yann@2076: Your configuration file for mercurial, e.g. ~/.hgrc should contain yann@2076: at least the following sections (but have a look at `man hgrc`): yann@2076: # --- yann@2076: [email] yann@2076: # configure sending patches directly via Mercurial yann@2076: from = "Your Name" yann@2076: # How to send email: yann@2076: method = smtp yann@2076: yann@2076: [smtp] yann@2076: # SMTP configuration (only for method=smtp) yann@2076: host = localhost yann@2076: tls = true yann@2076: username = yann@2076: password = yann@2076: yann@2076: [extensions] yann@2076: # The following lines enable the two extensions: yann@2076: hgext.mq = yann@2076: hgext.patchbomb = yann@2076: # ---- yann@2076: yann@2076: Create your local repository as a clone: yann@2076: hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng yann@2076: yann@2076: Setting up the mq extension in your local copy: yann@2076: cd crosstool-ng yann@2076: hg qinit yann@2076: yann@2076: yann@2076: CREATING PATCHES: yann@2076: yann@2076: Recording your changes in the patch queue maintained by mq: yann@2076: # First, create a new patch entry in the patch queue: yann@2076: hg qnew -D -U -e short_patch_name1 yann@2076: yann@2076: yann@2076: yann@2076: yann@2076: # if you execute `hg status` here, your modifications of the working yann@2076: # copy should show up. yann@2076: yann@2076: # Now the following command takes your modifications from the working copy yann@2076: # into the patch entry yann@2076: hg qrefresh -D [-e] yann@2076: yann@2076: yann@2076: # Now your changes are recorded, and `hg status` should show a clean yann@2076: # working copy yann@2076: yann@2076: Repeat the above steps for all your modifications. yann@2076: The command `hg qseries` informs you about the content of your patch queue. yann@2076: yann@2076: yann@2076: CONTRIBUTING YOUR PATCHES: yann@2076: yann@2076: Once you are satisfied with your patch series, you can (you should!) yann@2076: contribute them back to upstream. yann@2076: This is easily done using the `hg email` command. yann@2076: yann@2076: `hg email` sends your new changesets to a specified list of recipients, yann@2076: each patch in its own email, all ordered in the way you entered them (oldest yann@2076: first). The command line flag --outgoing selects all changesets that are in yann@2076: your local but not yet in the upstream repository. Here, these are exactly yann@2076: the ones you entered into your local patch queue in the section above, so yann@2076: --outgoing is what you want. yann@2076: yann@2076: Each email gets the subject set to: "[PATCH x of n] " yann@2076: where 'x' is the serial number in the email series, and 'n' is the total number yann@2076: of patches in the series. The body of the email is the complete patch, plus yann@2076: a handful of metadata, that helps properly apply the patch, keeping the log yann@2076: message, attribution and date, tracking file changes (move, delete, modes...) yann@2076: yann@2076: `hg email` also threads all outgoing patch emails below an introductory yann@2076: message. You should use the introductory message (command line flag --intro) yann@2076: to describe the scope and motivation for the whole patch series. The subject yann@2076: for the introductory message gets set to: "[PATCH 0 of n] " yann@2076: and you get the chance to set the . yann@2076: yann@2076: Here is a sample `hg email` complete command line: yann@2076: Note: replace " (at) " with "@" yann@2076: yann@2076: hg email --outgoing --intro \ yann@2076: --to '"Yann E. MORIN" ' \ yann@2076: --cc 'crossgcc (at) sourceware.org' yann@2076: yann@2076: # It then opens an editor and lets you enter the subject yann@2076: # and the body for the introductory message. yann@2076: yann@2076: Use `hg email` with the additional command line switch -n to yann@2076: first have a look at the email(s) without actually sending them. yann@2076: yann@2076: yann@2076: MAINTAINING YOUR PATCHES: yann@2076: yann@2076: When the patches are refined by discussing them on the mailing list, yann@2076: you may want to finalize and resend them. yann@2076: yann@2076: The mq extension has the idiosyncrasy of imposing a stack onto the queue: yann@2076: You can always reedit/refresh only the patch on top of stack. yann@2076: The queue consists of applied and unapplied patches yann@2076: (if you reached here via the above steps, all of your patches are applied), yann@2076: where the 'stack' consists of the applied patches, and 'top of stack' yann@2076: is the latest applied patch. yann@2076: yann@2076: The following output of `hg qseries` is now used as an example: yann@2076: 0 A short_patch_name1 yann@2076: 1 A short_patch_name2 yann@2076: 2 A short_patch_name3 yann@2076: 3 A short_patch_name4 yann@2076: yann@2076: You are now able to edit patch 'short_patch_name4' (which is top of stack): yann@2076: yann@2076: # and execute again yann@2076: hg qrefresh -D [-e] yann@2076: yann@2076: yann@2076: If you want to edit e.g. patch short_patch_name2, you have to modify yann@2076: mq's stack so this patch gets top of stack. yann@2076: For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`. yann@2076: yann@2076: hg qgoto short_patch_name2 yann@2076: # The patch queue should now look like yann@2076: hg qseries yann@2076: 0 A short_patch_name1 yann@2076: 1 A short_patch_name2 yann@2076: 2 U short_patch_name3 yann@2076: 3 U short_patch_name4 yann@2076: # so patch # 1 (short_patch_name2) is top of stack. yann@2076: yann@2076: # and execute again yann@2076: hg qrefresh -D [-e] yann@2076: yann@2076: # the following command reapplies the now unapplied two patches: yann@2076: hg qpush -a yann@2076: # you can also use `hg qgoto short_patch_name4` to get there again. yann@2076: yann@2076: yann@2076: RESENDING YOUR REEDITED PATCHES: yann@2076: yann@2076: By mailing list policy, please resend your complete patch series. yann@2076: --> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set. yann@2076: yann@2076: yann@2076: SYNCING WITH UPSTREAM AGAIN: yann@2076: yann@2076: You can sync your repo with upstream at any time by executing yann@2076: # first unapply all your patches: yann@2076: hg qpop -a yann@2076: # next fetch new changesets from upstream yann@2076: hg pull yann@2076: # then update your working copy yann@2076: hg up yann@2076: # optionally remove already upstream integrated patches (see below) yann@2076: hg qdelete yann@2076: # and reapply your patches if any non upstream-integrated left (but see below) yann@2076: hg qpush -a yann@2076: yann@2076: Eventually, your patches get included into the upstream repository yann@2076: which you initially cloned. yann@2076: In this case, before executing the hg qpush -a from above yann@2076: you should manually "hg qdelete" the patches that are already integrated upstream. yann@2076: yann@2076: yann@2076: HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions): yann@2076: yann@2076: Commit messages should look like (without leading pipes): yann@2076: |component: short, one-line description yann@2076: | yann@2076: |optional longer description yann@2076: |on multiple lines if needed yann@2076: yann@2076: Here is an example commit message (see revision a53a5e1d61db): yann@2076: |comp-libs/cloog: fix building yann@2076: | yann@2076: |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl. yann@2076: |For any later versions, the directory name does have the version, such as yann@2076: |cloog-ppl-0.15.4.