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.
|