]>
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 | ||
138 | How to add tags | |
139 | =============== | |
140 | ||
141 | To make this script useful you must add tags like the following into any | |
142 | commit. Most can only appear once in the whole series. | |
143 | ||
144 | Series-to: email / alias | |
2790bf69 WD |
145 | Email address / alias to send patch series to (you can add this |
146 | multiple times) | |
0d24de9d SG |
147 | |
148 | Series-cc: email / alias, ... | |
2790bf69 WD |
149 | Email address / alias to Cc patch series to (you can add this |
150 | multiple times) | |
0d24de9d SG |
151 | |
152 | Series-version: n | |
2790bf69 | 153 | Sets the version number of this patch series |
0d24de9d SG |
154 | |
155 | Series-prefix: prefix | |
2790bf69 | 156 | Sets the subject prefix. Normally empty but it can be RFC for |
3871cd85 WJ |
157 | RFC patches, or RESEND if you are being ignored. The patch subject |
158 | is like [RFC PATCH] or [RESEND PATCH]. | |
159 | In the meantime, git format.subjectprefix option will be added as | |
160 | well. If your format.subjectprefix is set to InternalProject, then | |
161 | the patch shows like: [InternalProject][RFC/RESEND PATCH] | |
0d24de9d | 162 | |
ef0e9de8 SG |
163 | Series-name: name |
164 | Sets the name of the series. You don't need to have a name, and | |
165 | patman does not yet use it, but it is convenient to put the branch | |
166 | name here to help you keep track of multiple upstreaming efforts. | |
167 | ||
0d24de9d SG |
168 | Cover-letter: |
169 | This is the patch set title | |
170 | blah blah | |
171 | more blah blah | |
172 | END | |
2790bf69 WD |
173 | Sets the cover letter contents for the series. The first line |
174 | will become the subject of the cover letter | |
0d24de9d | 175 | |
fe2f8d9e SG |
176 | Cover-letter-cc: email / alias |
177 | Additional email addresses / aliases to send cover letter to (you | |
178 | can add this multiple times) | |
179 | ||
0d24de9d SG |
180 | Series-notes: |
181 | blah blah | |
182 | blah blah | |
183 | more blah blah | |
184 | END | |
2790bf69 WD |
185 | Sets some notes for the patch series, which you don't want in |
186 | the commit messages, but do want to send, The notes are joined | |
187 | together and put after the cover letter. Can appear multiple | |
188 | times. | |
0d24de9d | 189 | |
5c8fdd91 AA |
190 | Commit-notes: |
191 | blah blah | |
192 | blah blah | |
193 | more blah blah | |
194 | END | |
195 | Similar, but for a single commit (patch). These notes will appear | |
196 | immediately below the --- cut in the patch file. | |
197 | ||
0d24de9d | 198 | Signed-off-by: Their Name <email> |
2790bf69 WD |
199 | A sign-off is added automatically to your patches (this is |
200 | probably a bug). If you put this tag in your patches, it will | |
201 | override the default signoff that patman automatically adds. | |
102061bd | 202 | Multiple duplicate signoffs will be removed. |
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 | |
659c89da SG |
228 | Patch-cc: Their Name <email> |
229 | This copies a single patch to another email address. Note that the | |
230 | Cc: used by git send-email is ignored by patman, but will be | |
231 | interpreted by git send-email if you use it. | |
0d24de9d | 232 | |
645b271a SG |
233 | Series-process-log: sort, uniq |
234 | This tells patman to sort and/or uniq the change logs. It is | |
235 | assumed that each change log entry is only a single line long. | |
236 | Use 'sort' to sort the entries, and 'uniq' to include only | |
237 | unique entries. If omitted, no change log processing is done. | |
238 | Separate each tag with a comma. | |
239 | ||
0d24de9d SG |
240 | Various other tags are silently removed, like these Chrome OS and |
241 | Gerrit tags: | |
242 | ||
243 | BUG=... | |
244 | TEST=... | |
245 | Change-Id: | |
246 | Review URL: | |
247 | Reviewed-on: | |
5c8fdd91 | 248 | Commit-xxxx: (except Commit-notes) |
0d24de9d SG |
249 | |
250 | Exercise for the reader: Try adding some tags to one of your current | |
251 | patch series and see how the patches turn out. | |
252 | ||
253 | ||
254 | Where Patches Are Sent | |
255 | ====================== | |
256 | ||
1713247f | 257 | Once the patches are created, patman sends them using git send-email. The |
0d24de9d | 258 | whole series is sent to the recipients in Series-to: and Series-cc. |
659c89da SG |
259 | You can Cc individual patches to other people with the Patch-cc: tag. Tags |
260 | in the subject are also picked up to Cc patches. For example, a commit like | |
261 | this: | |
0d24de9d SG |
262 | |
263 | >>>> | |
264 | commit 10212537b85ff9b6e09c82045127522c0f0db981 | |
265 | Author: Mike Frysinger <vapier@gentoo.org> | |
2790bf69 | 266 | Date: Mon Nov 7 23:18:44 2011 -0500 |
0d24de9d SG |
267 | |
268 | x86: arm: add a git mailrc file for maintainers | |
269 | ||
270 | This should make sending out e-mails to the right people easier. | |
271 | ||
659c89da SG |
272 | Patch-cc: sandbox, mikef, ag |
273 | Patch-cc: afleming | |
0d24de9d SG |
274 | <<<< |
275 | ||
276 | will create a patch which is copied to x86, arm, sandbox, mikef, ag and | |
277 | afleming. | |
278 | ||
659c89da SG |
279 | If you have a cover letter it will get sent to the union of the Patch-cc |
280 | lists of all of the other patches. If you want to sent it to additional | |
281 | people you can add a tag: | |
fe2f8d9e SG |
282 | |
283 | Cover-letter-cc: <list of addresses> | |
284 | ||
285 | These people will get the cover letter even if they are not on the To/Cc | |
286 | list for any of the patches. | |
31187255 | 287 | |
0d24de9d SG |
288 | |
289 | Example Work Flow | |
290 | ================= | |
291 | ||
292 | The basic workflow is to create your commits, add some tags to the top | |
293 | commit, and type 'patman' to check and send them. | |
294 | ||
295 | Here is an example workflow for a series of 4 patches. Let's say you have | |
296 | these rather contrived patches in the following order in branch us-cmd in | |
297 | your tree where 'us' means your upstreaming activity (newest to oldest as | |
298 | output by git log --oneline): | |
299 | ||
300 | 7c7909c wip | |
301 | 89234f5 Don't include standard parser if hush is used | |
302 | 8d640a7 mmc: sparc: Stop using builtin_run_command() | |
303 | 0c859a9 Rename run_command2() to run_command() | |
304 | a74443f sandbox: Rename run_command() to builtin_run_command() | |
305 | ||
306 | The first patch is some test things that enable your code to be compiled, | |
307 | but that you don't want to submit because there is an existing patch for it | |
308 | on the list. So you can tell patman to create and check some patches | |
309 | (skipping the first patch) with: | |
310 | ||
311 | patman -s1 -n | |
312 | ||
313 | If you want to do all of them including the work-in-progress one, then | |
314 | (if you are tracking an upstream branch): | |
315 | ||
316 | patman -n | |
317 | ||
318 | Let's say that patman reports an error in the second patch. Then: | |
319 | ||
320 | git rebase -i HEAD~6 | |
321 | <change 'pick' to 'edit' in 89234f5> | |
322 | <use editor to make code changes> | |
323 | git add -u | |
324 | git rebase --continue | |
325 | ||
326 | Now you have an updated patch series. To check it: | |
327 | ||
328 | patman -s1 -n | |
329 | ||
330 | Let's say it is now clean and you want to send it. Now you need to set up | |
331 | the destination. So amend the top commit with: | |
332 | ||
333 | git commit --amend | |
334 | ||
335 | Use your editor to add some tags, so that the whole commit message is: | |
336 | ||
337 | The current run_command() is really only one of the options, with | |
338 | hush providing the other. It really shouldn't be called directly | |
339 | in case the hush parser is bring used, so rename this function to | |
340 | better explain its purpose. | |
341 | ||
342 | Series-to: u-boot | |
343 | Series-cc: bfin, marex | |
344 | Series-prefix: RFC | |
345 | Cover-letter: | |
346 | Unified command execution in one place | |
347 | ||
348 | At present two parsers have similar code to execute commands. Also | |
349 | cmd_usage() is called all over the place. This series adds a single | |
350 | function which processes commands called cmd_process(). | |
351 | END | |
352 | ||
353 | Change-Id: Ica71a14c1f0ecb5650f771a32fecb8d2eb9d8a17 | |
354 | ||
355 | ||
356 | You want this to be an RFC and Cc the whole series to the bfin alias and | |
357 | to Marek. Two of the patches have tags (those are the bits at the front of | |
358 | the subject that say mmc: sparc: and sandbox:), so 8d640a7 will be Cc'd to | |
359 | mmc and sparc, and the last one to sandbox. | |
360 | ||
361 | Now to send the patches, take off the -n flag: | |
362 | ||
363 | patman -s1 | |
364 | ||
365 | The patches will be created, shown in your editor, and then sent along with | |
366 | the cover letter. Note that patman's tags are automatically removed so that | |
367 | people on the list don't see your secret info. | |
368 | ||
369 | Of course patches often attract comments and you need to make some updates. | |
370 | Let's say one person sent comments and you get an Acked-by: on one patch. | |
371 | Also, the patch on the list that you were waiting for has been merged, | |
372 | so you can drop your wip commit. So you resync with upstream: | |
373 | ||
2790bf69 | 374 | git fetch origin (or whatever upstream is called) |
0d24de9d SG |
375 | git rebase origin/master |
376 | ||
377 | and use git rebase -i to edit the commits, dropping the wip one. You add | |
378 | the ack tag to one commit: | |
379 | ||
380 | Acked-by: Heiko Schocher <hs@denx.de> | |
381 | ||
382 | update the Series-cc: in the top commit: | |
383 | ||
384 | Series-cc: bfin, marex, Heiko Schocher <hs@denx.de> | |
385 | ||
386 | and remove the Series-prefix: tag since it it isn't an RFC any more. The | |
387 | series is now version two, so the series info in the top commit looks like | |
388 | this: | |
389 | ||
390 | Series-to: u-boot | |
391 | Series-cc: bfin, marex, Heiko Schocher <hs@denx.de> | |
392 | Series-version: 2 | |
393 | Cover-letter: | |
394 | ... | |
395 | ||
396 | Finally, you need to add a change log to the two commits you changed. You | |
397 | add change logs to each individual commit where the changes happened, like | |
398 | this: | |
399 | ||
400 | Series-changes: 2 | |
401 | - Updated the command decoder to reduce code size | |
402 | - Wound the torque propounder up a little more | |
403 | ||
404 | (note the blank line at the end of the list) | |
405 | ||
406 | When you run patman it will collect all the change logs from the different | |
407 | commits and combine them into the cover letter, if you have one. So finally | |
408 | you have a new series of commits: | |
409 | ||
410 | faeb973 Don't include standard parser if hush is used | |
411 | 1b2f2fe mmc: sparc: Stop using builtin_run_command() | |
412 | cfbe330 Rename run_command2() to run_command() | |
413 | 0682677 sandbox: Rename run_command() to builtin_run_command() | |
414 | ||
415 | so to send them: | |
416 | ||
417 | patman | |
418 | ||
419 | and it will create and send the version 2 series. | |
420 | ||
421 | General points: | |
422 | ||
423 | 1. When you change back to the us-cmd branch days or weeks later all your | |
424 | information is still there, safely stored in the commits. You don't need | |
425 | to remember what version you are up to, who you sent the last lot of patches | |
426 | to, or anything about the change logs. | |
427 | ||
428 | 2. If you put tags in the subject, patman will Cc the maintainers | |
429 | automatically in many cases. | |
430 | ||
431 | 3. If you want to keep the commits from each series you sent so that you can | |
432 | compare change and see what you did, you can either create a new branch for | |
433 | each version, or just tag the branch before you start changing it: | |
434 | ||
435 | git tag sent/us-cmd-rfc | |
436 | ...later... | |
437 | git tag sent/us-cmd-v2 | |
438 | ||
439 | 4. If you want to modify the patches a little before sending, you can do | |
440 | this in your editor, but be careful! | |
441 | ||
442 | 5. If you want to run git send-email yourself, use the -n flag which will | |
443 | print out the command line patman would have used. | |
444 | ||
445 | 6. It is a good idea to add the change log info as you change the commit, | |
446 | not later when you can't remember which patch you changed. You can always | |
447 | go back and change or remove logs from commits. | |
448 | ||
449 | ||
450 | Other thoughts | |
451 | ============== | |
452 | ||
453 | This script has been split into sensible files but still needs work. | |
454 | Most of these are indicated by a TODO in the code. | |
455 | ||
456 | It would be nice if this could handle the In-reply-to side of things. | |
457 | ||
c8605bb4 GS |
458 | The tests are incomplete, as is customary. Use the --test flag to run them, |
459 | and make sure you are in the tools/patman directory first: | |
0d24de9d SG |
460 | |
461 | $ cd /path/to/u-boot | |
c8605bb4 GS |
462 | $ cd tools/patman |
463 | $ ./patman --test | |
0d24de9d SG |
464 | |
465 | Error handling doesn't always produce friendly error messages - e.g. | |
466 | putting an incorrect tag in a commit may provide a confusing message. | |
467 | ||
468 | There might be a few other features not mentioned in this README. They | |
469 | might be bugs. In particular, tags are case sensitive which is probably | |
470 | a bad thing. | |
471 | ||
472 | ||
473 | Simon Glass <sjg@chromium.org> | |
474 | v1, v2, 19-Oct-11 | |
475 | revised v3 24-Nov-11 |