docs: split into multiple files

The overview.txt file has evolved into more than just an overview.
Split it into chapters, and include the misc tutorials.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>

1 files changed, 226 insertions, 0 deletions

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