]>
Commit | Line | Data |
---|---|---|
0d24de9d SG |
1 | # Copyright (c) 2011 The Chromium OS Authors. |
2 | # | |
3 | # See file CREDITS for list of people who contributed to this | |
4 | # project. | |
5 | # | |
6 | # This program is free software; you can redistribute it and/or | |
7 | # modify it under the terms of the GNU General Public License as | |
8 | # published by the Free Software Foundation; either version 2 of | |
9 | # the License, or (at your option) any later version. | |
10 | # | |
11 | # This program is distributed in the hope that it will be useful, | |
12 | # but WITHOUT ANY WARRANTY; without even the implied warranty of | |
2790bf69 | 13 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
0d24de9d SG |
14 | # GNU General Public License for more details. |
15 | # | |
16 | # You should have received a copy of the GNU General Public License | |
17 | # along with this program; if not, write to the Free Software | |
18 | # Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
19 | # MA 02111-1307 USA | |
20 | # | |
21 | ||
22 | What is this? | |
23 | ============= | |
24 | ||
25 | This tool is a Python script which: | |
26 | - Creates patch directly from your branch | |
27 | - Cleans them up by removing unwanted tags | |
28 | - Inserts a cover letter with change lists | |
29 | - Runs the patches through checkpatch.pl and its own checks | |
30 | - Optionally emails them out to selected people | |
31 | ||
32 | It is intended to automate patch creation and make it a less | |
33 | error-prone process. It is useful for U-Boot and Linux work so far, | |
34 | since it uses the checkpatch.pl script. | |
35 | ||
36 | It is configured almost entirely by tags it finds in your commits. | |
37 | This means that you can work on a number of different branches at | |
38 | once, and keep the settings with each branch rather than having to | |
39 | git format-patch, git send-email, etc. with the correct parameters | |
40 | each time. So for example if you put: | |
41 | ||
42 | Series-to: fred.blogs@napier.co.nz | |
43 | ||
44 | in one of your commits, the series will be sent there. | |
45 | ||
21a19d70 DA |
46 | In Linux this will also call get_maintainer.pl on each of your |
47 | patches automatically. | |
48 | ||
0d24de9d SG |
49 | |
50 | How to use this tool | |
51 | ==================== | |
52 | ||
53 | This tool requires a certain way of working: | |
54 | ||
55 | - Maintain a number of branches, one for each patch series you are | |
56 | working on | |
57 | - Add tags into the commits within each branch to indicate where the | |
58 | series should be sent, cover letter, version, etc. Most of these are | |
59 | normally in the top commit so it is easy to change them with 'git | |
60 | commit --amend' | |
61 | - Each branch tracks the upstream branch, so that this script can | |
62 | automatically determine the number of commits in it (optional) | |
63 | - Check out a branch, and run this script to create and send out your | |
64 | patches. Weeks later, change the patches and repeat, knowing that you | |
65 | will get a consistent result each time. | |
66 | ||
67 | ||
68 | How to configure it | |
69 | =================== | |
70 | ||
ca706e76 | 71 | For most cases of using patman for U-Boot development, patman will |
21a19d70 DA |
72 | locate and use the file 'doc/git-mailrc' in your U-Boot directory. |
73 | This contains most of the aliases you will need. | |
74 | ||
75 | For Linux the 'scripts/get_maintainer.pl' handles figuring out where | |
76 | to send patches pretty well. | |
0d24de9d | 77 | |
87d65558 VN |
78 | During the first run patman creates a config file for you by taking the default |
79 | user name and email address from the global .gitconfig file. | |
80 | ||
2b36c75d | 81 | To add your own, create a file ~/.patman like this: |
0d24de9d SG |
82 | |
83 | >>>> | |
84 | # patman alias file | |
85 | ||
86 | [alias] | |
87 | me: Simon Glass <sjg@chromium.org> | |
88 | ||
89 | u-boot: U-Boot Mailing List <u-boot@lists.denx.de> | |
90 | wolfgang: Wolfgang Denk <wd@denx.de> | |
91 | others: Mike Frysinger <vapier@gentoo.org>, Fred Bloggs <f.bloggs@napier.net> | |
92 | ||
93 | <<<< | |
94 | ||
95 | Aliases are recursive. | |
96 | ||
97 | The checkpatch.pl in the U-Boot tools/ subdirectory will be located and | |
98 | used. Failing that you can put it into your path or ~/bin/checkpatch.pl | |
99 | ||
100 | ||
8568baed DA |
101 | If you want to change the defaults for patman's command-line arguments, |
102 | you can add a [settings] section to your .patman file. This can be used | |
103 | for any command line option by referring to the "dest" for the option in | |
104 | patman.py. For reference, the useful ones (at the moment) shown below | |
105 | (all with the non-default setting): | |
106 | ||
107 | >>> | |
108 | ||
109 | [settings] | |
110 | ignore_errors: True | |
111 | process_tags: False | |
112 | verbose: True | |
113 | ||
114 | <<< | |
115 | ||
116 | ||
a1dcee84 DA |
117 | If you want to adjust settings (or aliases) that affect just a single |
118 | project you can add a section that looks like [project_settings] or | |
119 | [project_alias]. If you want to use tags for your linux work, you could | |
120 | do: | |
121 | ||
122 | >>> | |
123 | ||
124 | [linux_settings] | |
125 | process_tags: True | |
126 | ||
127 | <<< | |
128 | ||
129 | ||
0d24de9d SG |
130 | How to run it |
131 | ============= | |
132 | ||
133 | First do a dry run: | |
134 | ||
330a091c | 135 | $ ./tools/patman/patman -n |
0d24de9d SG |
136 | |
137 | If it can't detect the upstream branch, try telling it how many patches | |
138 | there are in your series: | |
139 | ||
330a091c | 140 | $ ./tools/patman/patman -n -c5 |
0d24de9d SG |
141 | |
142 | This will create patch files in your current directory and tell you who | |
143 | it is thinking of sending them to. Take a look at the patch files. | |
144 | ||
330a091c | 145 | $ ./tools/patman/patman -n -c5 -s1 |
0d24de9d SG |
146 | |
147 | Similar to the above, but skip the first commit and take the next 5. This | |
148 | is useful if your top commit is for setting up testing. | |
149 | ||
150 | ||
151 | How to add tags | |
152 | =============== | |
153 | ||
154 | To make this script useful you must add tags like the following into any | |
155 | commit. Most can only appear once in the whole series. | |
156 | ||
157 | Series-to: email / alias | |
2790bf69 WD |
158 | Email address / alias to send patch series to (you can add this |
159 | multiple times) | |
0d24de9d SG |
160 | |
161 | Series-cc: email / alias, ... | |
2790bf69 WD |
162 | Email address / alias to Cc patch series to (you can add this |
163 | multiple times) | |
0d24de9d SG |
164 | |
165 | Series-version: n | |
2790bf69 | 166 | Sets the version number of this patch series |
0d24de9d SG |
167 | |
168 | Series-prefix: prefix | |
2790bf69 WD |
169 | Sets the subject prefix. Normally empty but it can be RFC for |
170 | RFC patches, or RESEND if you are being ignored. | |
0d24de9d | 171 | |
ef0e9de8 SG |
172 | Series-name: name |
173 | Sets the name of the series. You don't need to have a name, and | |
174 | patman does not yet use it, but it is convenient to put the branch | |
175 | name here to help you keep track of multiple upstreaming efforts. | |
176 | ||
0d24de9d SG |
177 | Cover-letter: |
178 | This is the patch set title | |
179 | blah blah | |
180 | more blah blah | |
181 | END | |
2790bf69 WD |
182 | Sets the cover letter contents for the series. The first line |
183 | will become the subject of the cover letter | |
0d24de9d | 184 | |
fe2f8d9e SG |
185 | Cover-letter-cc: email / alias |
186 | Additional email addresses / aliases to send cover letter to (you | |
187 | can add this multiple times) | |
188 | ||
0d24de9d SG |
189 | Series-notes: |
190 | blah blah | |
191 | blah blah | |
192 | more blah blah | |
193 | END | |
2790bf69 WD |
194 | Sets some notes for the patch series, which you don't want in |
195 | the commit messages, but do want to send, The notes are joined | |
196 | together and put after the cover letter. Can appear multiple | |
197 | times. | |
0d24de9d SG |
198 | |
199 | Signed-off-by: Their Name <email> | |
2790bf69 WD |
200 | A sign-off is added automatically to your patches (this is |
201 | probably a bug). If you put this tag in your patches, it will | |
202 | override the default signoff that patman automatically adds. | |
0d24de9d SG |
203 | |
204 | Tested-by: Their Name <email> | |
28b3594e | 205 | Reviewed-by: Their Name <email> |
0d24de9d | 206 | Acked-by: Their Name <email> |
28b3594e | 207 | These indicate that someone has tested/reviewed/acked your patch. |
2790bf69 WD |
208 | When you get this reply on the mailing list, you can add this |
209 | tag to the relevant commit and the script will include it when | |
210 | you send out the next version. If 'Tested-by:' is set to | |
211 | yourself, it will be removed. No one will believe you. | |
0d24de9d SG |
212 | |
213 | Series-changes: n | |
214 | - Guinea pig moved into its cage | |
215 | - Other changes ending with a blank line | |
216 | <blank line> | |
2790bf69 WD |
217 | This can appear in any commit. It lists the changes for a |
218 | particular version n of that commit. The change list is | |
219 | created based on this information. Each commit gets its own | |
220 | change list and also the whole thing is repeated in the cover | |
221 | letter (where duplicate change lines are merged). | |
0d24de9d | 222 | |
2790bf69 WD |
223 | By adding your change lists into your commits it is easier to |
224 | keep track of what happened. When you amend a commit, remember | |
225 | to update the log there and then, knowing that the script will | |
226 | do the rest. | |
0d24de9d | 227 | |
645b271a | 228 | Cc: Their Name <email> |
2790bf69 | 229 | This copies a single patch to another email address. |
0d24de9d | 230 | |
645b271a SG |
231 | Series-process-log: sort, uniq |
232 | This tells patman to sort and/or uniq the change logs. It is | |
233 | assumed that each change log entry is only a single line long. | |
234 | Use 'sort' to sort the entries, and 'uniq' to include only | |
235 | unique entries. If omitted, no change log processing is done. | |
236 | Separate each tag with a comma. | |
237 | ||
0d24de9d SG |
238 | Various other tags are silently removed, like these Chrome OS and |
239 | Gerrit tags: | |
240 | ||
241 | BUG=... | |
242 | TEST=... | |
243 | Change-Id: | |
244 | Review URL: | |
245 | Reviewed-on: | |
0d24de9d SG |
246 | |
247 | ||
248 | Exercise for the reader: Try adding some tags to one of your current | |
249 | patch series and see how the patches turn out. | |
250 | ||
251 | ||
252 | Where Patches Are Sent | |
253 | ====================== | |
254 | ||
1713247f | 255 | Once the patches are created, patman sends them using git send-email. The |
0d24de9d SG |
256 | whole series is sent to the recipients in Series-to: and Series-cc. |
257 | You can Cc individual patches to other people with the Cc: tag. Tags in the | |
258 | subject are also picked up to Cc patches. For example, a commit like this: | |
259 | ||
260 | >>>> | |
261 | commit 10212537b85ff9b6e09c82045127522c0f0db981 | |
262 | Author: Mike Frysinger <vapier@gentoo.org> | |
2790bf69 | 263 | Date: Mon Nov 7 23:18:44 2011 -0500 |
0d24de9d SG |
264 | |
265 | x86: arm: add a git mailrc file for maintainers | |
266 | ||
267 | This should make sending out e-mails to the right people easier. | |
268 | ||
269 | Cc: sandbox, mikef, ag | |
270 | Cc: afleming | |
271 | <<<< | |
272 | ||
273 | will create a patch which is copied to x86, arm, sandbox, mikef, ag and | |
274 | afleming. | |
275 | ||
31187255 | 276 | If you have a cover letter it will get sent to the union of the CC lists of |
fe2f8d9e SG |
277 | all of the other patches. If you want to sent it to additional people you |
278 | can add a tag: | |
279 | ||
280 | Cover-letter-cc: <list of addresses> | |
281 | ||
282 | These people will get the cover letter even if they are not on the To/Cc | |
283 | list for any of the patches. | |
31187255 | 284 | |
0d24de9d SG |
285 | |
286 | Example Work Flow | |
287 | ================= | |
288 | ||
289 | The basic workflow is to create your commits, add some tags to the top | |
290 | commit, and type 'patman' to check and send them. | |
291 | ||
292 | Here is an example workflow for a series of 4 patches. Let's say you have | |
293 | these rather contrived patches in the following order in branch us-cmd in | |
294 | your tree where 'us' means your upstreaming activity (newest to oldest as | |
295 | output by git log --oneline): | |
296 | ||
297 | 7c7909c wip | |
298 | 89234f5 Don't include standard parser if hush is used | |
299 | 8d640a7 mmc: sparc: Stop using builtin_run_command() | |
300 | 0c859a9 Rename run_command2() to run_command() | |
301 | a74443f sandbox: Rename run_command() to builtin_run_command() | |
302 | ||
303 | The first patch is some test things that enable your code to be compiled, | |
304 | but that you don't want to submit because there is an existing patch for it | |
305 | on the list. So you can tell patman to create and check some patches | |
306 | (skipping the first patch) with: | |
307 | ||
308 | patman -s1 -n | |
309 | ||
310 | If you want to do all of them including the work-in-progress one, then | |
311 | (if you are tracking an upstream branch): | |
312 | ||
313 | patman -n | |
314 | ||
315 | Let's say that patman reports an error in the second patch. Then: | |
316 | ||
317 | git rebase -i HEAD~6 | |
318 | <change 'pick' to 'edit' in 89234f5> | |
319 | <use editor to make code changes> | |
320 | git add -u | |
321 | git rebase --continue | |
322 | ||
323 | Now you have an updated patch series. To check it: | |
324 | ||
325 | patman -s1 -n | |
326 | ||
327 | Let's say it is now clean and you want to send it. Now you need to set up | |
328 | the destination. So amend the top commit with: | |
329 | ||
330 | git commit --amend | |
331 | ||
332 | Use your editor to add some tags, so that the whole commit message is: | |
333 | ||
334 | The current run_command() is really only one of the options, with | |
335 | hush providing the other. It really shouldn't be called directly | |
336 | in case the hush parser is bring used, so rename this function to | |
337 | better explain its purpose. | |
338 | ||
339 | Series-to: u-boot | |
340 | Series-cc: bfin, marex | |
341 | Series-prefix: RFC | |
342 | Cover-letter: | |
343 | Unified command execution in one place | |
344 | ||
345 | At present two parsers have similar code to execute commands. Also | |
346 | cmd_usage() is called all over the place. This series adds a single | |
347 | function which processes commands called cmd_process(). | |
348 | END | |
349 | ||
350 | Change-Id: Ica71a14c1f0ecb5650f771a32fecb8d2eb9d8a17 | |
351 | ||
352 | ||
353 | You want this to be an RFC and Cc the whole series to the bfin alias and | |
354 | to Marek. Two of the patches have tags (those are the bits at the front of | |
355 | the subject that say mmc: sparc: and sandbox:), so 8d640a7 will be Cc'd to | |
356 | mmc and sparc, and the last one to sandbox. | |
357 | ||
358 | Now to send the patches, take off the -n flag: | |
359 | ||
360 | patman -s1 | |
361 | ||
362 | The patches will be created, shown in your editor, and then sent along with | |
363 | the cover letter. Note that patman's tags are automatically removed so that | |
364 | people on the list don't see your secret info. | |
365 | ||
366 | Of course patches often attract comments and you need to make some updates. | |
367 | Let's say one person sent comments and you get an Acked-by: on one patch. | |
368 | Also, the patch on the list that you were waiting for has been merged, | |
369 | so you can drop your wip commit. So you resync with upstream: | |
370 | ||
2790bf69 | 371 | git fetch origin (or whatever upstream is called) |
0d24de9d SG |
372 | git rebase origin/master |
373 | ||
374 | and use git rebase -i to edit the commits, dropping the wip one. You add | |
375 | the ack tag to one commit: | |
376 | ||
377 | Acked-by: Heiko Schocher <hs@denx.de> | |
378 | ||
379 | update the Series-cc: in the top commit: | |
380 | ||
381 | Series-cc: bfin, marex, Heiko Schocher <hs@denx.de> | |
382 | ||
383 | and remove the Series-prefix: tag since it it isn't an RFC any more. The | |
384 | series is now version two, so the series info in the top commit looks like | |
385 | this: | |
386 | ||
387 | Series-to: u-boot | |
388 | Series-cc: bfin, marex, Heiko Schocher <hs@denx.de> | |
389 | Series-version: 2 | |
390 | Cover-letter: | |
391 | ... | |
392 | ||
393 | Finally, you need to add a change log to the two commits you changed. You | |
394 | add change logs to each individual commit where the changes happened, like | |
395 | this: | |
396 | ||
397 | Series-changes: 2 | |
398 | - Updated the command decoder to reduce code size | |
399 | - Wound the torque propounder up a little more | |
400 | ||
401 | (note the blank line at the end of the list) | |
402 | ||
403 | When you run patman it will collect all the change logs from the different | |
404 | commits and combine them into the cover letter, if you have one. So finally | |
405 | you have a new series of commits: | |
406 | ||
407 | faeb973 Don't include standard parser if hush is used | |
408 | 1b2f2fe mmc: sparc: Stop using builtin_run_command() | |
409 | cfbe330 Rename run_command2() to run_command() | |
410 | 0682677 sandbox: Rename run_command() to builtin_run_command() | |
411 | ||
412 | so to send them: | |
413 | ||
414 | patman | |
415 | ||
416 | and it will create and send the version 2 series. | |
417 | ||
418 | General points: | |
419 | ||
420 | 1. When you change back to the us-cmd branch days or weeks later all your | |
421 | information is still there, safely stored in the commits. You don't need | |
422 | to remember what version you are up to, who you sent the last lot of patches | |
423 | to, or anything about the change logs. | |
424 | ||
425 | 2. If you put tags in the subject, patman will Cc the maintainers | |
426 | automatically in many cases. | |
427 | ||
428 | 3. If you want to keep the commits from each series you sent so that you can | |
429 | compare change and see what you did, you can either create a new branch for | |
430 | each version, or just tag the branch before you start changing it: | |
431 | ||
432 | git tag sent/us-cmd-rfc | |
433 | ...later... | |
434 | git tag sent/us-cmd-v2 | |
435 | ||
436 | 4. If you want to modify the patches a little before sending, you can do | |
437 | this in your editor, but be careful! | |
438 | ||
439 | 5. If you want to run git send-email yourself, use the -n flag which will | |
440 | print out the command line patman would have used. | |
441 | ||
442 | 6. It is a good idea to add the change log info as you change the commit, | |
443 | not later when you can't remember which patch you changed. You can always | |
444 | go back and change or remove logs from commits. | |
445 | ||
446 | ||
447 | Other thoughts | |
448 | ============== | |
449 | ||
450 | This script has been split into sensible files but still needs work. | |
451 | Most of these are indicated by a TODO in the code. | |
452 | ||
453 | It would be nice if this could handle the In-reply-to side of things. | |
454 | ||
c8605bb4 GS |
455 | The tests are incomplete, as is customary. Use the --test flag to run them, |
456 | and make sure you are in the tools/patman directory first: | |
0d24de9d SG |
457 | |
458 | $ cd /path/to/u-boot | |
c8605bb4 GS |
459 | $ cd tools/patman |
460 | $ ./patman --test | |
0d24de9d SG |
461 | |
462 | Error handling doesn't always produce friendly error messages - e.g. | |
463 | putting an incorrect tag in a commit may provide a confusing message. | |
464 | ||
465 | There might be a few other features not mentioned in this README. They | |
466 | might be bugs. In particular, tags are case sensitive which is probably | |
467 | a bad thing. | |
468 | ||
469 | ||
470 | Simon Glass <sjg@chromium.org> | |
471 | v1, v2, 19-Oct-11 | |
472 | revised v3 24-Nov-11 |