docs/7 - Contributing to crosstool-NG.txt
author "Yann E. MORIN" <yann.morin.1998@anciens.enib.fr>
Sat Aug 14 16:37:11 2010 +0200 (2010-08-14)
changeset 2076 b58109b7b321
child 2077 b11117cdfdf7
permissions -rw-r--r--
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>
yann@2076
     1
File.........: 7 - Contributing to crosstool-NG.txt
yann@2076
     2
Copyrigth....: (C) 2010 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
yann@2076
     3
License......: Creative Commons Attribution Share Alike (CC-by-sa), v2.5
yann@2076
     4
yann@2076
     5
yann@2076
     6
Contributing to crosstool-NG  /
yann@2076
     7
_____________________________/
yann@2076
     8
yann@2076
     9
yann@2076
    10
Sending a bug report |
yann@2076
    11
---------------------+
yann@2076
    12
yann@2076
    13
If you need to send a bug report, please send a mail with subject
yann@2076
    14
prefixed with "[CT_NG]" with to following destinations:
yann@2076
    15
    TO: yann.morin.1998 (at) anciens.enib.fr
yann@2076
    16
    CC: crossgcc (at) sourceware.org
yann@2076
    17
yann@2076
    18
yann@2076
    19
Sending patches |
yann@2076
    20
----------------+
yann@2076
    21
yann@2076
    22
If you want to enhance crosstool-NG, there's a to-do list in the TODO file.
yann@2076
    23
yann@2076
    24
Patches should come with the appropriate SoB line. A SoB line is typically
yann@2076
    25
something like:
yann@2076
    26
   Signed-off-by: John DOE <john.doe@somewhere.net>
yann@2076
    27
yann@2076
    28
The SoB line is clearly described in Documentation/SubmittingPatches , section
yann@2076
    29
12, of your favourite Linux kernel source tree.
yann@2076
    30
yann@2076
    31
yann@2076
    32
How to Use Mercurial |
yann@2076
    33
---------------------+
yann@2076
    34
yann@2076
    35
For larger or more frequent contributions, mercurial should be used.
yann@2076
    36
yann@2076
    37
PREREQUISITES:
yann@2076
    38
yann@2076
    39
Configuring Mercurial:
yann@2076
    40
  You need mercurial with the following extensions:
yann@2076
    41
   - mq        : http://mercurial.selenic.com/wiki/MqExtension
yann@2076
    42
   - patchbomb : http://mercurial.selenic.com/wiki/PatchbombExtension
yann@2076
    43
  Usually, these two extensions are already part of the installation package.
yann@2076
    44
  The mq extension maintains a separate queue of your local changes
yann@2076
    45
  that you can change at any later time.
yann@2076
    46
  With the patchbomb extension you can email those patches directly
yann@2076
    47
  from your local repo.
yann@2076
    48
yann@2076
    49
  Your configuration file for mercurial, e.g. ~/.hgrc should contain
yann@2076
    50
  at least the following sections (but have a look at `man hgrc`):
yann@2076
    51
  # ---
yann@2076
    52
  [email]
yann@2076
    53
  # configure sending patches directly via Mercurial
yann@2076
    54
  from = "Your Name" <your@email.address>
yann@2076
    55
  # How to send email:
yann@2076
    56
  method = smtp
yann@2076
    57
yann@2076
    58
  [smtp]
yann@2076
    59
  # SMTP configuration (only for method=smtp)
yann@2076
    60
  host = localhost
yann@2076
    61
  tls = true
yann@2076
    62
  username =
yann@2076
    63
  password =
yann@2076
    64
yann@2076
    65
  [extensions]
yann@2076
    66
  # The following lines enable the two extensions:
yann@2076
    67
  hgext.mq =
yann@2076
    68
  hgext.patchbomb =
yann@2076
    69
  # ----
yann@2076
    70
yann@2076
    71
Create your local repository as a clone:
yann@2076
    72
  hg clone http://ymorin.is-a-geek.org/hg/crosstool-ng crosstool-ng
yann@2076
    73
yann@2076
    74
Setting up the mq extension in your local copy:
yann@2076
    75
  cd crosstool-ng
yann@2076
    76
  hg qinit
yann@2076
    77
yann@2076
    78
yann@2076
    79
CREATING PATCHES:
yann@2076
    80
yann@2076
    81
Recording your changes in the patch queue maintained by mq:
yann@2076
    82
  # First, create a new patch entry in the patch queue:
yann@2076
    83
  hg qnew -D -U -e short_patch_name1
yann@2076
    84
  <edit patch description as commit message (see below for an example)>
yann@2076
    85
yann@2076
    86
  <now edit the ct-ng sources and check them>
yann@2076
    87
yann@2076
    88
  # if you execute `hg status` here, your modifications of the working
yann@2076
    89
  # copy should show up.
yann@2076
    90
yann@2076
    91
  # Now the following command takes your modifications from the working copy
yann@2076
    92
  # into the patch entry
yann@2076
    93
  hg qrefresh -D [-e]
yann@2076
    94
  <reedit patch description [-e] if desired>
yann@2076
    95
yann@2076
    96
  # Now your changes are recorded, and `hg status` should show a clean
yann@2076
    97
  # working copy
yann@2076
    98
yann@2076
    99
Repeat the above steps for all your modifications.
yann@2076
   100
The command `hg qseries` informs you about the content of your patch queue.
yann@2076
   101
yann@2076
   102
yann@2076
   103
CONTRIBUTING YOUR PATCHES:
yann@2076
   104
yann@2076
   105
Once you are satisfied with your patch series, you can (you should!)
yann@2076
   106
contribute them back to upstream.
yann@2076
   107
This is easily done using the `hg email` command.
yann@2076
   108
yann@2076
   109
`hg email` sends your new changesets to a specified list of recipients,
yann@2076
   110
each patch in its own email, all ordered in the way you entered them (oldest
yann@2076
   111
first). The command line flag --outgoing selects all changesets that are in
yann@2076
   112
your local but not yet in the upstream repository. Here, these are exactly
yann@2076
   113
the ones you entered into your local patch queue in the section above, so
yann@2076
   114
--outgoing is what you want.
yann@2076
   115
yann@2076
   116
Each email gets the subject set to:  "[PATCH x of n] <series summary>"
yann@2076
   117
where 'x' is the serial number in the email series, and 'n' is the total number
yann@2076
   118
of patches in the series. The body of the email is the complete patch, plus
yann@2076
   119
a handful of metadata, that helps properly apply the patch, keeping the log
yann@2076
   120
message, attribution and date, tracking file changes (move, delete, modes...)
yann@2076
   121
yann@2076
   122
`hg email` also threads all outgoing patch emails below an introductory
yann@2076
   123
message. You should use the introductory message (command line flag --intro)
yann@2076
   124
to describe the scope and motivation for the whole patch series. The subject
yann@2076
   125
for the introductory message gets set to:  "[PATCH 0 of n] <series summary>"
yann@2076
   126
and you get the chance to set the <series summary>.
yann@2076
   127
yann@2076
   128
Here is a sample `hg email` complete command line:
yann@2076
   129
Note: replace " (at) " with "@"
yann@2076
   130
yann@2076
   131
  hg email --outgoing --intro   \
yann@2076
   132
           --to '"Yann E. MORIN" <yann.morin.1998 (at) anciens.enib.fr>'    \
yann@2076
   133
           --cc 'crossgcc (at) sourceware.org'
yann@2076
   134
yann@2076
   135
  # It then opens an editor and lets you enter the subject
yann@2076
   136
  # and the body for the introductory message.
yann@2076
   137
yann@2076
   138
Use `hg email` with the additional command line switch -n to
yann@2076
   139
first have a look at the email(s) without actually sending them.
yann@2076
   140
yann@2076
   141
yann@2076
   142
MAINTAINING YOUR PATCHES:
yann@2076
   143
yann@2076
   144
When the patches are refined by discussing them on the mailing list,
yann@2076
   145
you may want to finalize and resend them.
yann@2076
   146
yann@2076
   147
The mq extension has the idiosyncrasy of imposing a stack onto the queue:
yann@2076
   148
You can always reedit/refresh only the patch on top of stack.
yann@2076
   149
The queue consists of applied and unapplied patches
yann@2076
   150
(if you reached here via the above steps, all of your patches are applied),
yann@2076
   151
where the 'stack' consists of the applied patches, and 'top of stack'
yann@2076
   152
is the latest applied patch.
yann@2076
   153
yann@2076
   154
The following output of `hg qseries` is now used as an example:
yann@2076
   155
  0 A short_patch_name1
yann@2076
   156
  1 A short_patch_name2
yann@2076
   157
  2 A short_patch_name3
yann@2076
   158
  3 A short_patch_name4
yann@2076
   159
yann@2076
   160
You are now able to edit patch 'short_patch_name4' (which is top of stack):
yann@2076
   161
  <Edit the sources>
yann@2076
   162
  # and execute again
yann@2076
   163
  hg qrefresh -D [-e]
yann@2076
   164
  <and optionally [-e] reedit the commit message>
yann@2076
   165
yann@2076
   166
If you want to edit e.g. patch short_patch_name2, you have to modify
yann@2076
   167
mq's stack so this patch gets top of stack.
yann@2076
   168
For this purpose see `hg help qgoto`, `hg help qpop`, and `hg help qpush`.
yann@2076
   169
yann@2076
   170
  hg qgoto short_patch_name2
yann@2076
   171
  # The patch queue should now look like
yann@2076
   172
  hg qseries
yann@2076
   173
    0 A short_patch_name1
yann@2076
   174
    1 A short_patch_name2
yann@2076
   175
    2 U short_patch_name3
yann@2076
   176
    3 U short_patch_name4
yann@2076
   177
  # so patch # 1 (short_patch_name2) is top of stack.
yann@2076
   178
  <now reedit the sources for short_patch_name2>
yann@2076
   179
  # and execute again
yann@2076
   180
  hg qrefresh -D [-e]
yann@2076
   181
  <and optionally [-e] reedit the commit message>
yann@2076
   182
  # the following command reapplies the now unapplied two patches:
yann@2076
   183
  hg qpush -a
yann@2076
   184
  # you can also use `hg qgoto short_patch_name4` to get there again.
yann@2076
   185
yann@2076
   186
yann@2076
   187
RESENDING YOUR REEDITED PATCHES:
yann@2076
   188
yann@2076
   189
By mailing list policy, please resend your complete patch series.
yann@2076
   190
--> Go back to section "CONTRIBUTING YOUR PATCHES" and resubmit the full set.
yann@2076
   191
yann@2076
   192
yann@2076
   193
SYNCING WITH UPSTREAM AGAIN:
yann@2076
   194
yann@2076
   195
You can sync your repo with upstream at any time by executing
yann@2076
   196
  # first unapply all your patches:
yann@2076
   197
  hg qpop -a
yann@2076
   198
  # next fetch new changesets from upstream
yann@2076
   199
  hg pull
yann@2076
   200
  # then update your working copy
yann@2076
   201
  hg up
yann@2076
   202
  # optionally remove already upstream integrated patches (see below)
yann@2076
   203
  hg qdelete <short_name_of_already_applied_patch>
yann@2076
   204
  # and reapply your patches if any non upstream-integrated left (but see below)
yann@2076
   205
  hg qpush -a
yann@2076
   206
yann@2076
   207
Eventually, your patches get included into the upstream repository
yann@2076
   208
which you initially cloned.
yann@2076
   209
In this case, before executing the hg qpush -a from above
yann@2076
   210
you should manually "hg qdelete" the patches that are already integrated upstream.
yann@2076
   211
yann@2076
   212
yann@2076
   213
HOW TO FORMAT COMMIT MESSAGES (aka patch desciptions):
yann@2076
   214
yann@2076
   215
Commit messages should look like (without leading pipes):
yann@2076
   216
 |component: short, one-line description
yann@2076
   217
 |
yann@2076
   218
 |optional longer description
yann@2076
   219
 |on multiple lines if needed
yann@2076
   220
yann@2076
   221
Here is an example commit message (see revision a53a5e1d61db):
yann@2076
   222
 |comp-libs/cloog: fix building
yann@2076
   223
 |
yann@2076
   224
 |For CLooG/PPL 0.15.3, the directory name was simply cloog-ppl.
yann@2076
   225
 |For any later versions, the directory name does have the version, such as
yann@2076
   226
 |cloog-ppl-0.15.4.