xref: /openbmc/u-boot/tools/patman/README (revision 67cf22cb)
1# SPDX-License-Identifier: GPL-2.0+
2# Copyright (c) 2011 The Chromium OS Authors.
3
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
28In Linux and U-Boot this will also call get_maintainer.pl on each of your
29patches automatically (unless you use -m to disable this).
30
31
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
53For 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:
57
58    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.
62
63During 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
66To add your own, create a file ~/.patman like this:
67
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
85If 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
97
98If 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
110smtp_server: /path/to/sendmail
111
112<<<
113
114
115If 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
128How to run it
129=============
130
131First do a dry run:
132
133$ ./tools/patman/patman -n
134
135If it can't detect the upstream branch, try telling it how many patches
136there are in your series:
137
138$ ./tools/patman/patman -n -c5
139
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
143$ ./tools/patman/patman -n -c5 -s1
144
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
149How to install it
150=================
151
152The most up to date version of patman can be found in the U-Boot sources.
153However 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
160How 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
167	Email address / alias to send patch series to (you can add this
168	multiple times)
169
170Series-cc: email / alias, ...
171	Email address / alias to Cc patch series to (you can add this
172	multiple times)
173
174Series-version: n
175	Sets the version number of this patch series
176
177Series-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
185Series-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
190Cover-letter:
191This is the patch set title
192blah blah
193more blah blah
194END
195	Sets the cover letter contents for the series. The first line
196	will become the subject of the cover letter
197
198Cover-letter-cc: email / alias
199	Additional email addresses / aliases to send cover letter to (you
200	can add this multiple times)
201
202Series-notes:
203blah blah
204blah blah
205more blah blah
206END
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
212Commit-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
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
235Series-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
250Patch-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
255Series-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
262Various other tags are silently removed, like these Chrome OS and
263Gerrit tags:
264
265BUG=...
266TEST=...
267Change-Id:
268Review URL:
269Reviewed-on:
270Commit-xxxx: (except Commit-notes)
271
272Exercise for the reader: Try adding some tags to one of your current
273patch series and see how the patches turn out.
274
275
276Where Patches Are Sent
277======================
278
279Once the patches are created, patman sends them using git send-email. The
280whole series is sent to the recipients in Series-to: and Series-cc.
281You can Cc individual patches to other people with the Patch-cc: tag. Tags
282in the subject are also picked up to Cc patches. For example, a commit like
283this:
284
285>>>>
286commit 10212537b85ff9b6e09c82045127522c0f0db981
287Author: Mike Frysinger <vapier@gentoo.org>
288Date:	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
298will create a patch which is copied to x86, arm, sandbox, mikef, ag and
299afleming.
300
301If you have a cover letter it will get sent to the union of the Patch-cc
302lists of all of the other patches. If you want to sent it to additional
303people you can add a tag:
304
305Cover-letter-cc: <list of addresses>
306
307These people will get the cover letter even if they are not on the To/Cc
308list for any of the patches.
309
310
311Example Work Flow
312=================
313
314The basic workflow is to create your commits, add some tags to the top
315commit, and type 'patman' to check and send them.
316
317Here is an example workflow for a series of 4 patches. Let's say you have
318these rather contrived patches in the following order in branch us-cmd in
319your tree where 'us' means your upstreaming activity (newest to oldest as
320output 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
328The first patch is some test things that enable your code to be compiled,
329but that you don't want to submit because there is an existing patch for it
330on 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
335If 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
340Let'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
348Now you have an updated patch series. To check it:
349
350    patman -s1 -n
351
352Let's say it is now clean and you want to send it. Now you need to set up
353the destination. So amend the top commit with:
354
355    git commit --amend
356
357Use 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
378You want this to be an RFC and Cc the whole series to the bfin alias and
379to Marek. Two of the patches have tags (those are the bits at the front of
380the subject that say mmc: sparc: and sandbox:), so 8d640a7 will be Cc'd to
381mmc and sparc, and the last one to sandbox.
382
383Now to send the patches, take off the -n flag:
384
385   patman -s1
386
387The patches will be created, shown in your editor, and then sent along with
388the cover letter. Note that patman's tags are automatically removed so that
389people on the list don't see your secret info.
390
391Of course patches often attract comments and you need to make some updates.
392Let's say one person sent comments and you get an Acked-by: on one patch.
393Also, the patch on the list that you were waiting for has been merged,
394so 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
399and use git rebase -i to edit the commits, dropping the wip one. You add
400the ack tag to one commit:
401
402    Acked-by: Heiko Schocher <hs@denx.de>
403
404update the Series-cc: in the top commit:
405
406    Series-cc: bfin, marex, Heiko Schocher <hs@denx.de>
407
408and remove the Series-prefix: tag since it it isn't an RFC any more. The
409series is now version two, so the series info in the top commit looks like
410this:
411
412    Series-to: u-boot
413    Series-cc: bfin, marex, Heiko Schocher <hs@denx.de>
414    Series-version: 2
415    Cover-letter:
416    ...
417
418Finally, you need to add a change log to the two commits you changed. You
419add change logs to each individual commit where the changes happened, like
420this:
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
428When you run patman it will collect all the change logs from the different
429commits and combine them into the cover letter, if you have one. So finally
430you 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
437so to send them:
438
439    patman
440
441and it will create and send the version 2 series.
442
443General points:
444
4451. When you change back to the us-cmd branch days or weeks later all your
446information is still there, safely stored in the commits. You don't need
447to remember what version you are up to, who you sent the last lot of patches
448to, or anything about the change logs.
449
4502. If you put tags in the subject, patman will Cc the maintainers
451automatically in many cases.
452
4533. If you want to keep the commits from each series you sent so that you can
454compare change and see what you did, you can either create a new branch for
455each 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
4614. If you want to modify the patches a little before sending, you can do
462this in your editor, but be careful!
463
4645. If you want to run git send-email yourself, use the -n flag which will
465print out the command line patman would have used.
466
4676. It is a good idea to add the change log info as you change the commit,
468not later when you can't remember which patch you changed. You can always
469go back and change or remove logs from commits.
470
471
472Other thoughts
473==============
474
475This script has been split into sensible files but still needs work.
476Most of these are indicated by a TODO in the code.
477
478It would be nice if this could handle the In-reply-to side of things.
479
480The tests are incomplete, as is customary. Use the --test flag to run them,
481and 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
487Error handling doesn't always produce friendly error messages - e.g.
488putting an incorrect tag in a commit may provide a confusing message.
489
490There might be a few other features not mentioned in this README. They
491might be bugs. In particular, tags are case sensitive which is probably
492a bad thing.
493
494
495Simon Glass <sjg@chromium.org>
496v1, v2, 19-Oct-11
497revised v3 24-Nov-11
498