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