blob: 52b2cf70bd0e58416205ee6e4e810c03652c3f90 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001# SPDX-License-Identifier: GPL-2.0+
Simon Glass0d24de92012-01-14 15:12:45 +00002# Copyright (c) 2011 The Chromium OS Authors.
Simon Glass0d24de92012-01-14 15:12:45 +00003
4What is this?
5=============
6
7This 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
14It is intended to automate patch creation and make it a less
15error-prone process. It is useful for U-Boot and Linux work so far,
16since it uses the checkpatch.pl script.
17
18It is configured almost entirely by tags it finds in your commits.
19This means that you can work on a number of different branches at
20once, and keep the settings with each branch rather than having to
21git format-patch, git send-email, etc. with the correct parameters
22each time. So for example if you put:
23
24Series-to: fred.blogs@napier.co.nz
25
26in one of your commits, the series will be sent there.
27
Simon Glass983a2742014-09-14 20:23:17 -060028In Linux and U-Boot this will also call get_maintainer.pl on each of your
29patches automatically (unless you use -m to disable this).
Doug Anderson21a19d72012-12-03 14:43:16 +000030
Simon Glass0d24de92012-01-14 15:12:45 +000031
32How to use this tool
33====================
34
35This tool requires a certain way of working:
36
37- Maintain a number of branches, one for each patch series you are
38working on
39- Add tags into the commits within each branch to indicate where the
40series should be sent, cover letter, version, etc. Most of these are
41normally in the top commit so it is easy to change them with 'git
42commit --amend'
43- Each branch tracks the upstream branch, so that this script can
44automatically determine the number of commits in it (optional)
45- Check out a branch, and run this script to create and send out your
46patches. Weeks later, change the patches and repeat, knowing that you
47will get a consistent result each time.
48
49
50How to configure it
51===================
52
Simon Glass3d4de982014-10-03 20:40:36 -060053For most cases of using patman for U-Boot development, patman can use the
54file 'doc/git-mailrc' in your U-Boot directory to supply the email aliases
55you need. To make this work, tell git where to find the file by typing
56this once:
Doug Anderson21a19d72012-12-03 14:43:16 +000057
Simon Glass3d4de982014-10-03 20:40:36 -060058 git config sendemail.aliasesfile doc/git-mailrc
59
60For both Linux and U-Boot the 'scripts/get_maintainer.pl' handles figuring
61out where to send patches pretty well.
Simon Glass0d24de92012-01-14 15:12:45 +000062
Vikram Narayanan87d65552012-05-23 09:01:06 +000063During the first run patman creates a config file for you by taking the default
64user name and email address from the global .gitconfig file.
65
Vikram Narayanan2b36c752012-05-23 08:58:58 +000066To add your own, create a file ~/.patman like this:
Simon Glass0d24de92012-01-14 15:12:45 +000067
68>>>>
69# patman alias file
70
71[alias]
72me: Simon Glass <sjg@chromium.org>
73
74u-boot: U-Boot Mailing List <u-boot@lists.denx.de>
75wolfgang: Wolfgang Denk <wd@denx.de>
76others: Mike Frysinger <vapier@gentoo.org>, Fred Bloggs <f.bloggs@napier.net>
77
78<<<<
79
80Aliases are recursive.
81
82The checkpatch.pl in the U-Boot tools/ subdirectory will be located and
83used. Failing that you can put it into your path or ~/bin/checkpatch.pl
84
Chris Packhame11aa602017-09-01 20:57:53 +120085If you want to avoid sending patches to email addresses that are picked up
86by 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
88that are not recursive.
89
90>>>
91
92[bounces]
93gonefishing: Fred Bloggs <f.bloggs@napier.net>
94
95<<<
96
Simon Glass0d24de92012-01-14 15:12:45 +000097
Doug Anderson8568bae2012-12-03 14:43:17 +000098If you want to change the defaults for patman's command-line arguments,
99you can add a [settings] section to your .patman file. This can be used
100for any command line option by referring to the "dest" for the option in
101patman.py. For reference, the useful ones (at the moment) shown below
102(all with the non-default setting):
103
104>>>
105
106[settings]
107ignore_errors: True
108process_tags: False
109verbose: True
Simon Glassa60aedf2018-06-19 09:56:07 -0600110smtp_server: /path/to/sendmail
Doug Anderson8568bae2012-12-03 14:43:17 +0000111
112<<<
113
114
Doug Andersona1dcee82012-12-03 14:43:18 +0000115If you want to adjust settings (or aliases) that affect just a single
116project 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
118do:
119
120>>>
121
122[linux_settings]
123process_tags: True
124
125<<<
126
127
Simon Glass0d24de92012-01-14 15:12:45 +0000128How to run it
129=============
130
131First do a dry run:
132
Vikram Narayanan330a0912012-04-27 06:39:31 +0000133$ ./tools/patman/patman -n
Simon Glass0d24de92012-01-14 15:12:45 +0000134
135If it can't detect the upstream branch, try telling it how many patches
136there are in your series:
137
Vikram Narayanan330a0912012-04-27 06:39:31 +0000138$ ./tools/patman/patman -n -c5
Simon Glass0d24de92012-01-14 15:12:45 +0000139
140This will create patch files in your current directory and tell you who
141it is thinking of sending them to. Take a look at the patch files.
142
Vikram Narayanan330a0912012-04-27 06:39:31 +0000143$ ./tools/patman/patman -n -c5 -s1
Simon Glass0d24de92012-01-14 15:12:45 +0000144
145Similar to the above, but skip the first commit and take the next 5. This
146is useful if your top commit is for setting up testing.
147
148
Chris Packham488d19c2015-07-22 21:21:46 +1200149How to install it
150=================
151
Bin Menga1875592016-02-05 19:30:11 -0800152The most up to date version of patman can be found in the U-Boot sources.
Chris Packham488d19c2015-07-22 21:21:46 +1200153However to use it on other projects it may be more convenient to install it as
154a standalone application. A distutils installer is included, this can be used
155to install patman:
156
157$ cd tools/patman && python setup.py install
158
159
Simon Glass0d24de92012-01-14 15:12:45 +0000160How to add tags
161===============
162
163To make this script useful you must add tags like the following into any
164commit. Most can only appear once in the whole series.
165
166Series-to: email / alias
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200167 Email address / alias to send patch series to (you can add this
168 multiple times)
Simon Glass0d24de92012-01-14 15:12:45 +0000169
170Series-cc: email / alias, ...
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200171 Email address / alias to Cc patch series to (you can add this
172 multiple times)
Simon Glass0d24de92012-01-14 15:12:45 +0000173
174Series-version: n
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200175 Sets the version number of this patch series
Simon Glass0d24de92012-01-14 15:12:45 +0000176
177Series-prefix: prefix
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200178 Sets the subject prefix. Normally empty but it can be RFC for
Wu, Josh3871cd82015-04-15 10:25:18 +0800179 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]
Simon Glass0d24de92012-01-14 15:12:45 +0000184
Simon Glassef0e9de2012-09-27 15:06:02 +0000185Series-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
Simon Glass0d24de92012-01-14 15:12:45 +0000190Cover-letter:
191This is the patch set title
192blah blah
193more blah blah
194END
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200195 Sets the cover letter contents for the series. The first line
196 will become the subject of the cover letter
Simon Glass0d24de92012-01-14 15:12:45 +0000197
Simon Glassfe2f8d92013-03-20 16:43:00 +0000198Cover-letter-cc: email / alias
199 Additional email addresses / aliases to send cover letter to (you
200 can add this multiple times)
201
Simon Glass0d24de92012-01-14 15:12:45 +0000202Series-notes:
203blah blah
204blah blah
205more blah blah
206END
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200207 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.
Simon Glass0d24de92012-01-14 15:12:45 +0000211
Albert ARIBAUD5c8fdd92013-11-12 11:14:41 +0100212Commit-notes:
213blah blah
214blah blah
215more blah blah
216END
217 Similar, but for a single commit (patch). These notes will appear
218 immediately below the --- cut in the patch file.
219
Simon Glass0d24de92012-01-14 15:12:45 +0000220 Signed-off-by: Their Name <email>
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200221 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.
Simon Glass102061b2014-04-20 10:50:14 -0600224 Multiple duplicate signoffs will be removed.
Simon Glass0d24de92012-01-14 15:12:45 +0000225
226 Tested-by: Their Name <email>
Doug Anderson28b35942013-03-15 13:24:05 +0000227 Reviewed-by: Their Name <email>
Simon Glass0d24de92012-01-14 15:12:45 +0000228 Acked-by: Their Name <email>
Doug Anderson28b35942013-03-15 13:24:05 +0000229 These indicate that someone has tested/reviewed/acked your patch.
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200230 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.
Simon Glass0d24de92012-01-14 15:12:45 +0000234
235Series-changes: n
236- Guinea pig moved into its cage
237- Other changes ending with a blank line
238<blank line>
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200239 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).
Simon Glass0d24de92012-01-14 15:12:45 +0000244
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200245 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.
Simon Glass0d24de92012-01-14 15:12:45 +0000249
Sean Anderson6949f702020-05-04 16:28:34 -0400250Commit-changes: n
251- This line will not appear in the cover-letter changelog
252<blank line>
253 This tag is like Series-changes, except changes in this changelog will
254 only appear in the changelog of the commit this tag is in. This is
255 useful when you want to add notes which may not make sense in the cover
256 letter. For example, you can have short changes such as "New" or
257 "Lint".
258
259Cover-changes: n
260- This line will only appear in the cover letter
261<blank line>
262 This tag is like Series-changes, except changes in this changelog will
263 only appear in the cover-letter changelog. This is useful to summarize
264 changes made with Commit-changes, or to add additional context to
265 changes.
266
Simon Glass659c89d2014-02-16 08:23:47 -0700267Patch-cc: Their Name <email>
268 This copies a single patch to another email address. Note that the
269 Cc: used by git send-email is ignored by patman, but will be
270 interpreted by git send-email if you use it.
Simon Glass0d24de92012-01-14 15:12:45 +0000271
Simon Glass645b2712013-03-26 13:09:44 +0000272Series-process-log: sort, uniq
Sean Anderson0411fff2020-05-04 16:28:35 -0400273 This tells patman to sort and/or uniq the change logs. Changes may be
274 multiple lines long, as long as each subsequent line of a change begins
275 with a whitespace character. For example,
276
277- This change
278 continues onto the next line
279- But this change is separate
280
Simon Glass645b2712013-03-26 13:09:44 +0000281 Use 'sort' to sort the entries, and 'uniq' to include only
282 unique entries. If omitted, no change log processing is done.
283 Separate each tag with a comma.
284
Douglas Anderson833e4192019-09-27 09:23:56 -0700285Change-Id:
286 This tag is stripped out but is used to generate the Message-Id
287 of the emails that will be sent. When you keep the Change-Id the
288 same you are asserting that this is a slightly different version
289 (but logically the same patch) as other patches that have been
290 sent out with the same Change-Id.
291
Simon Glass0d24de92012-01-14 15:12:45 +0000292Various other tags are silently removed, like these Chrome OS and
293Gerrit tags:
294
295BUG=...
296TEST=...
Simon Glass0d24de92012-01-14 15:12:45 +0000297Review URL:
298Reviewed-on:
Albert ARIBAUD5c8fdd92013-11-12 11:14:41 +0100299Commit-xxxx: (except Commit-notes)
Simon Glass0d24de92012-01-14 15:12:45 +0000300
301Exercise for the reader: Try adding some tags to one of your current
302patch series and see how the patches turn out.
303
304
305Where Patches Are Sent
306======================
307
Vikram Narayanan17132472012-04-25 05:45:05 +0000308Once the patches are created, patman sends them using git send-email. The
Simon Glass0d24de92012-01-14 15:12:45 +0000309whole series is sent to the recipients in Series-to: and Series-cc.
Simon Glass659c89d2014-02-16 08:23:47 -0700310You can Cc individual patches to other people with the Patch-cc: tag. Tags
311in the subject are also picked up to Cc patches. For example, a commit like
312this:
Simon Glass0d24de92012-01-14 15:12:45 +0000313
314>>>>
315commit 10212537b85ff9b6e09c82045127522c0f0db981
316Author: Mike Frysinger <vapier@gentoo.org>
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200317Date: Mon Nov 7 23:18:44 2011 -0500
Simon Glass0d24de92012-01-14 15:12:45 +0000318
319 x86: arm: add a git mailrc file for maintainers
320
321 This should make sending out e-mails to the right people easier.
322
Simon Glass659c89d2014-02-16 08:23:47 -0700323 Patch-cc: sandbox, mikef, ag
324 Patch-cc: afleming
Simon Glass0d24de92012-01-14 15:12:45 +0000325<<<<
326
327will create a patch which is copied to x86, arm, sandbox, mikef, ag and
328afleming.
329
Simon Glass659c89d2014-02-16 08:23:47 -0700330If you have a cover letter it will get sent to the union of the Patch-cc
331lists of all of the other patches. If you want to sent it to additional
332people you can add a tag:
Simon Glassfe2f8d92013-03-20 16:43:00 +0000333
334Cover-letter-cc: <list of addresses>
335
336These people will get the cover letter even if they are not on the To/Cc
337list for any of the patches.
Doug Anderson31187252012-12-03 14:40:43 +0000338
Simon Glass0d24de92012-01-14 15:12:45 +0000339
340Example Work Flow
341=================
342
343The basic workflow is to create your commits, add some tags to the top
344commit, and type 'patman' to check and send them.
345
346Here is an example workflow for a series of 4 patches. Let's say you have
347these rather contrived patches in the following order in branch us-cmd in
348your tree where 'us' means your upstreaming activity (newest to oldest as
349output by git log --oneline):
350
351 7c7909c wip
352 89234f5 Don't include standard parser if hush is used
353 8d640a7 mmc: sparc: Stop using builtin_run_command()
354 0c859a9 Rename run_command2() to run_command()
355 a74443f sandbox: Rename run_command() to builtin_run_command()
356
357The first patch is some test things that enable your code to be compiled,
358but that you don't want to submit because there is an existing patch for it
359on the list. So you can tell patman to create and check some patches
360(skipping the first patch) with:
361
362 patman -s1 -n
363
364If you want to do all of them including the work-in-progress one, then
365(if you are tracking an upstream branch):
366
367 patman -n
368
369Let's say that patman reports an error in the second patch. Then:
370
371 git rebase -i HEAD~6
372 <change 'pick' to 'edit' in 89234f5>
373 <use editor to make code changes>
374 git add -u
375 git rebase --continue
376
377Now you have an updated patch series. To check it:
378
379 patman -s1 -n
380
381Let's say it is now clean and you want to send it. Now you need to set up
382the destination. So amend the top commit with:
383
384 git commit --amend
385
386Use your editor to add some tags, so that the whole commit message is:
387
388 The current run_command() is really only one of the options, with
389 hush providing the other. It really shouldn't be called directly
390 in case the hush parser is bring used, so rename this function to
391 better explain its purpose.
392
393 Series-to: u-boot
394 Series-cc: bfin, marex
395 Series-prefix: RFC
396 Cover-letter:
397 Unified command execution in one place
398
399 At present two parsers have similar code to execute commands. Also
400 cmd_usage() is called all over the place. This series adds a single
401 function which processes commands called cmd_process().
402 END
403
404 Change-Id: Ica71a14c1f0ecb5650f771a32fecb8d2eb9d8a17
405
406
407You want this to be an RFC and Cc the whole series to the bfin alias and
408to Marek. Two of the patches have tags (those are the bits at the front of
409the subject that say mmc: sparc: and sandbox:), so 8d640a7 will be Cc'd to
410mmc and sparc, and the last one to sandbox.
411
412Now to send the patches, take off the -n flag:
413
414 patman -s1
415
416The patches will be created, shown in your editor, and then sent along with
417the cover letter. Note that patman's tags are automatically removed so that
418people on the list don't see your secret info.
419
420Of course patches often attract comments and you need to make some updates.
421Let's say one person sent comments and you get an Acked-by: on one patch.
422Also, the patch on the list that you were waiting for has been merged,
423so you can drop your wip commit. So you resync with upstream:
424
Wolfgang Denk2790bf62012-04-21 18:55:26 +0200425 git fetch origin (or whatever upstream is called)
Simon Glass0d24de92012-01-14 15:12:45 +0000426 git rebase origin/master
427
428and use git rebase -i to edit the commits, dropping the wip one. You add
429the ack tag to one commit:
430
431 Acked-by: Heiko Schocher <hs@denx.de>
432
433update the Series-cc: in the top commit:
434
435 Series-cc: bfin, marex, Heiko Schocher <hs@denx.de>
436
437and remove the Series-prefix: tag since it it isn't an RFC any more. The
438series is now version two, so the series info in the top commit looks like
439this:
440
441 Series-to: u-boot
442 Series-cc: bfin, marex, Heiko Schocher <hs@denx.de>
443 Series-version: 2
444 Cover-letter:
445 ...
446
447Finally, you need to add a change log to the two commits you changed. You
448add change logs to each individual commit where the changes happened, like
449this:
450
451 Series-changes: 2
452 - Updated the command decoder to reduce code size
453 - Wound the torque propounder up a little more
454
455(note the blank line at the end of the list)
456
457When you run patman it will collect all the change logs from the different
458commits and combine them into the cover letter, if you have one. So finally
459you have a new series of commits:
460
461 faeb973 Don't include standard parser if hush is used
462 1b2f2fe mmc: sparc: Stop using builtin_run_command()
463 cfbe330 Rename run_command2() to run_command()
464 0682677 sandbox: Rename run_command() to builtin_run_command()
465
466so to send them:
467
468 patman
469
470and it will create and send the version 2 series.
471
472General points:
473
4741. When you change back to the us-cmd branch days or weeks later all your
475information is still there, safely stored in the commits. You don't need
476to remember what version you are up to, who you sent the last lot of patches
477to, or anything about the change logs.
478
4792. If you put tags in the subject, patman will Cc the maintainers
480automatically in many cases.
481
4823. If you want to keep the commits from each series you sent so that you can
483compare change and see what you did, you can either create a new branch for
484each version, or just tag the branch before you start changing it:
485
486 git tag sent/us-cmd-rfc
487 ...later...
488 git tag sent/us-cmd-v2
489
4904. If you want to modify the patches a little before sending, you can do
491this in your editor, but be careful!
492
4935. If you want to run git send-email yourself, use the -n flag which will
494print out the command line patman would have used.
495
4966. It is a good idea to add the change log info as you change the commit,
497not later when you can't remember which patch you changed. You can always
498go back and change or remove logs from commits.
499
Bin Meng14aa35a2020-05-04 00:52:44 -07005007. Some mailing lists have size limits and when we add binary contents to
501our patches it's easy to exceed the size limits. Use "--no-binary" to
502generate patches without any binary contents. You are supposed to include
503a link to a git repository in your "Commit-notes", "Series-notes" or
504"Cover-letter" for maintainers to fetch the original commit.
Simon Glass0d24de92012-01-14 15:12:45 +0000505
Sean Andersonb0436b92020-05-04 16:28:33 -04005068. Patches will have no changelog entries for revisions where they did not
507change. For clarity, if there are no changes for this patch in the most
508recent revision of the series, a note will be added. For example, a patch
509with the following tags in the commit
510
511 Series-version: 5
512 Series-changes: 2
513 - Some change
514
515 Series-changes: 4
516 - Another change
517
518would have a changelog of
519
520 (no changes since v4)
521
522 Changes in v4:
523 - Another change
524
525 Changes in v2:
526 - Some change
527
Simon Glass0d24de92012-01-14 15:12:45 +0000528Other thoughts
529==============
530
531This script has been split into sensible files but still needs work.
532Most of these are indicated by a TODO in the code.
533
534It would be nice if this could handle the In-reply-to side of things.
535
Gerhard Sittigc8605bb2013-07-14 11:27:45 +0200536The tests are incomplete, as is customary. Use the --test flag to run them,
537and make sure you are in the tools/patman directory first:
Simon Glass0d24de92012-01-14 15:12:45 +0000538
539 $ cd /path/to/u-boot
Gerhard Sittigc8605bb2013-07-14 11:27:45 +0200540 $ cd tools/patman
541 $ ./patman --test
Simon Glass0d24de92012-01-14 15:12:45 +0000542
543Error handling doesn't always produce friendly error messages - e.g.
544putting an incorrect tag in a commit may provide a confusing message.
545
546There might be a few other features not mentioned in this README. They
547might be bugs. In particular, tags are case sensitive which is probably
548a bad thing.
549
550
551Simon Glass <sjg@chromium.org>
552v1, v2, 19-Oct-11
553revised v3 24-Nov-11