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