2022-08-09 19:49:57 +00:00
|
|
|
.. SPDX-License-Identifier: GPL-2.0+
|
|
|
|
.. Copyright (c) 2011 The Chromium OS Authors
|
|
|
|
.. Simon Glass <sjg@chromium.org>
|
2022-12-20 05:28:46 +00:00
|
|
|
.. Maxim Cournoyer <maxim.cournoyer@savoirfairelinux.com>
|
2022-08-09 19:49:57 +00:00
|
|
|
.. v1, v2, 19-Oct-11
|
|
|
|
.. revised v3 24-Nov-11
|
2022-08-17 18:47:06 +00:00
|
|
|
.. revised v4 Independence Day 2020, with Patchwork integration
|
2022-08-09 19:49:57 +00:00
|
|
|
|
|
|
|
Patman patch manager
|
|
|
|
====================
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
This tool is a Python script which:
|
2022-08-09 19:49:57 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
- Creates patch directly from your branch
|
|
|
|
- Cleans them up by removing unwanted tags
|
|
|
|
- Inserts a cover letter with change lists
|
|
|
|
- Runs the patches through checkpatch.pl and its own checks
|
|
|
|
- Optionally emails them out to selected people
|
|
|
|
|
2020-10-30 03:46:36 +00:00
|
|
|
It also has some Patchwork features:
|
2022-08-09 19:49:57 +00:00
|
|
|
|
2020-10-30 03:46:36 +00:00
|
|
|
- shows review tags from Patchwork so you can update your local patches
|
|
|
|
- pulls these down into a new branch on request
|
2020-10-30 03:46:38 +00:00
|
|
|
- lists comments received on a series
|
2020-10-30 03:46:35 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
It is intended to automate patch creation and make it a less
|
|
|
|
error-prone process. It is useful for U-Boot and Linux work so far,
|
2020-10-30 03:46:36 +00:00
|
|
|
since they use the checkpatch.pl script.
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
It is configured almost entirely by tags it finds in your commits.
|
|
|
|
This means that you can work on a number of different branches at
|
|
|
|
once, and keep the settings with each branch rather than having to
|
|
|
|
git format-patch, git send-email, etc. with the correct parameters
|
2022-08-09 19:49:57 +00:00
|
|
|
each time. So for example if you put::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Series-to: fred.blogs@napier.co.nz
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
in one of your commits, the series will be sent there.
|
|
|
|
|
2014-09-15 02:23:17 +00:00
|
|
|
In Linux and U-Boot this will also call get_maintainer.pl on each of your
|
|
|
|
patches automatically (unless you use -m to disable this).
|
2012-12-03 14:43:16 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2023-02-24 01:18:23 +00:00
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
|
|
|
You can install patman using::
|
|
|
|
|
|
|
|
pip install patch-manager
|
|
|
|
|
|
|
|
The name is chosen since patman conflicts with an existing package.
|
|
|
|
|
|
|
|
If you are using patman within the U-Boot tree, it may be easiest to add a
|
|
|
|
symlink from your local `~/.bin` directory to `/path/to/tools/patman/patman`.
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
How to use this tool
|
2022-08-09 19:49:57 +00:00
|
|
|
--------------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
This tool requires a certain way of working:
|
|
|
|
|
|
|
|
- Maintain a number of branches, one for each patch series you are
|
2022-08-09 19:49:57 +00:00
|
|
|
working on
|
2012-01-14 15:12:45 +00:00
|
|
|
- Add tags into the commits within each branch to indicate where the
|
2022-08-09 19:49:57 +00:00
|
|
|
series should be sent, cover letter, version, etc. Most of these are
|
|
|
|
normally in the top commit so it is easy to change them with 'git
|
|
|
|
commit --amend'
|
2012-01-14 15:12:45 +00:00
|
|
|
- Each branch tracks the upstream branch, so that this script can
|
2022-08-09 19:49:57 +00:00
|
|
|
automatically determine the number of commits in it (optional)
|
2012-01-14 15:12:45 +00:00
|
|
|
- Check out a branch, and run this script to create and send out your
|
2022-08-09 19:49:57 +00:00
|
|
|
patches. Weeks later, change the patches and repeat, knowing that you
|
|
|
|
will get a consistent result each time.
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
|
|
|
|
How to configure it
|
2022-08-09 19:49:57 +00:00
|
|
|
-------------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2014-10-04 02:40:36 +00:00
|
|
|
For most cases of using patman for U-Boot development, patman can use the
|
|
|
|
file 'doc/git-mailrc' in your U-Boot directory to supply the email aliases
|
|
|
|
you need. To make this work, tell git where to find the file by typing
|
2022-08-09 19:49:57 +00:00
|
|
|
this once::
|
2012-12-03 14:43:16 +00:00
|
|
|
|
2014-10-04 02:40:36 +00:00
|
|
|
git config sendemail.aliasesfile doc/git-mailrc
|
|
|
|
|
2022-12-20 05:28:46 +00:00
|
|
|
For both Linux and U-Boot the 'scripts/get_maintainer.pl' handles
|
|
|
|
figuring out where to send patches pretty well. For other projects,
|
|
|
|
you may want to specify a different script to be run, for example via
|
|
|
|
a project-specific `.patman` file::
|
|
|
|
|
|
|
|
# .patman configuration file at the root of some project
|
|
|
|
|
|
|
|
[settings]
|
|
|
|
get_maintainer_script: etc/teams.scm get-maintainer
|
|
|
|
|
|
|
|
The `get_maintainer_script` option corresponds to the
|
|
|
|
`--get-maintainer-script` argument of the `send` command. It is
|
|
|
|
looked relatively to the root of the current git repository, as well
|
|
|
|
as on PATH. It can also be provided arguments, as shown above. The
|
|
|
|
contract is that the script should accept a patch file name and return
|
|
|
|
a list of email addresses, one per line, like `get_maintainer.pl`
|
|
|
|
does.
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2012-05-23 09:01:06 +00:00
|
|
|
During the first run patman creates a config file for you by taking the default
|
|
|
|
user name and email address from the global .gitconfig file.
|
|
|
|
|
2022-12-20 05:38:41 +00:00
|
|
|
To add your own, create a file `~/.patman` like this::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
# patman alias file
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
[alias]
|
|
|
|
me: Simon Glass <sjg@chromium.org>
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
u-boot: U-Boot Mailing List <u-boot@lists.denx.de>
|
|
|
|
wolfgang: Wolfgang Denk <wd@denx.de>
|
|
|
|
others: Mike Frysinger <vapier@gentoo.org>, Fred Bloggs <f.bloggs@napier.net>
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-12-20 05:28:46 +00:00
|
|
|
As hinted above, Patman will also look for a `.patman` configuration
|
|
|
|
file at the root of the current project git repository, which makes it
|
|
|
|
possible to override the `project` settings variable or anything else
|
|
|
|
in a project-specific way. The values of this "local" configuration
|
|
|
|
file take precedence over those of the "global" one.
|
2022-12-20 05:38:41 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Aliases are recursive.
|
|
|
|
|
|
|
|
The checkpatch.pl in the U-Boot tools/ subdirectory will be located and
|
|
|
|
used. Failing that you can put it into your path or ~/bin/checkpatch.pl
|
|
|
|
|
2017-09-01 08:57:53 +00:00
|
|
|
If you want to avoid sending patches to email addresses that are picked up
|
|
|
|
by patman but are known to bounce you can add a [bounces] section to your
|
|
|
|
.patman file. Unlike the [alias] section these are simple key: value pairs
|
2022-08-09 19:49:57 +00:00
|
|
|
that are not recursive::
|
2017-09-01 08:57:53 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
[bounces]
|
|
|
|
gonefishing: Fred Bloggs <f.bloggs@napier.net>
|
2017-09-01 08:57:53 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2012-12-03 14:43:17 +00:00
|
|
|
If you want to change the defaults for patman's command-line arguments,
|
|
|
|
you can add a [settings] section to your .patman file. This can be used
|
|
|
|
for any command line option by referring to the "dest" for the option in
|
|
|
|
patman.py. For reference, the useful ones (at the moment) shown below
|
2022-08-09 19:49:57 +00:00
|
|
|
(all with the non-default setting)::
|
2012-12-03 14:43:17 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
[settings]
|
|
|
|
ignore_errors: True
|
|
|
|
process_tags: False
|
|
|
|
verbose: True
|
|
|
|
smtp_server: /path/to/sendmail
|
|
|
|
patchwork_server: https://patchwork.ozlabs.org
|
2012-12-03 14:43:17 +00:00
|
|
|
|
2012-12-03 14:43:18 +00:00
|
|
|
If you want to adjust settings (or aliases) that affect just a single
|
|
|
|
project you can add a section that looks like [project_settings] or
|
2022-08-09 19:49:57 +00:00
|
|
|
[project_alias]. If you want to use tags for your linux work, you could do::
|
2012-12-03 14:43:18 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
[linux_settings]
|
|
|
|
process_tags: True
|
2012-12-03 14:43:18 +00:00
|
|
|
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
How to run it
|
2022-08-09 19:49:57 +00:00
|
|
|
-------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
First do a dry run:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
./tools/patman/patman send -n
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
If it can't detect the upstream branch, try telling it how many patches
|
2022-08-09 19:49:57 +00:00
|
|
|
there are in your series
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
./tools/patman/patman -c5 send -n
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
This will create patch files in your current directory and tell you who
|
2022-08-09 19:49:57 +00:00
|
|
|
it is thinking of sending them to. Take a look at the patch files:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
./tools/patman/patman -c5 -s1 send -n
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Similar to the above, but skip the first commit and take the next 5. This
|
|
|
|
is useful if your top commit is for setting up testing.
|
|
|
|
|
|
|
|
|
2015-07-22 09:21:46 +00:00
|
|
|
How to install it
|
2022-08-09 19:49:57 +00:00
|
|
|
-----------------
|
2015-07-22 09:21:46 +00:00
|
|
|
|
2016-02-06 03:30:11 +00:00
|
|
|
The most up to date version of patman can be found in the U-Boot sources.
|
2015-07-22 09:21:46 +00:00
|
|
|
However to use it on other projects it may be more convenient to install it as
|
|
|
|
a standalone application. A distutils installer is included, this can be used
|
|
|
|
to install patman:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
cd tools/patman && python setup.py install
|
2015-07-22 09:21:46 +00:00
|
|
|
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
How to add tags
|
2022-08-09 19:49:57 +00:00
|
|
|
---------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
To make this script useful you must add tags like the following into any
|
|
|
|
commit. Most can only appear once in the whole series.
|
|
|
|
|
|
|
|
Series-to: email / alias
|
2022-08-09 19:49:57 +00:00
|
|
|
Email address / alias to send patch series to (you can add this
|
|
|
|
multiple times)
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-cc: email / alias, ...
|
2022-08-09 19:49:57 +00:00
|
|
|
Email address / alias to Cc patch series to (you can add this
|
|
|
|
multiple times)
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-version: n
|
2022-08-09 19:49:57 +00:00
|
|
|
Sets the version number of this patch series
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-prefix: prefix
|
2022-08-09 19:49:57 +00:00
|
|
|
Sets the subject prefix. Normally empty but it can be RFC for
|
|
|
|
RFC patches, or RESEND if you are being ignored. The patch subject
|
|
|
|
is like [RFC PATCH] or [RESEND PATCH].
|
|
|
|
In the meantime, git format.subjectprefix option will be added as
|
|
|
|
well. If your format.subjectprefix is set to InternalProject, then
|
|
|
|
the patch shows like: [InternalProject][RFC/RESEND PATCH]
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2021-10-22 23:07:04 +00:00
|
|
|
Series-postfix: postfix
|
2022-08-09 19:49:57 +00:00
|
|
|
Sets the subject "postfix". Normally empty, but can be the name of a
|
|
|
|
tree such as net or net-next if that needs to be specified. The patch
|
|
|
|
subject is like [PATCH net] or [PATCH net-next].
|
2021-10-22 23:07:04 +00:00
|
|
|
|
2012-09-27 15:06:02 +00:00
|
|
|
Series-name: name
|
2022-08-09 19:49:57 +00:00
|
|
|
Sets the name of the series. You don't need to have a name, and
|
|
|
|
patman does not yet use it, but it is convenient to put the branch
|
|
|
|
name here to help you keep track of multiple upstreaming efforts.
|
2012-09-27 15:06:02 +00:00
|
|
|
|
2020-10-30 03:46:16 +00:00
|
|
|
Series-links: [id | version:id]...
|
2022-08-09 19:49:57 +00:00
|
|
|
Set the ID of the series in patchwork. You can set this after you send
|
|
|
|
out the series and look in patchwork for the resulting series. The
|
|
|
|
URL you want is the one for the series itself, not any particular patch.
|
|
|
|
E.g. for http://patchwork.ozlabs.org/project/uboot/list/?series=187331
|
|
|
|
the series ID is 187331. This property can have a list of series IDs,
|
|
|
|
one for each version of the series, e.g.
|
|
|
|
|
|
|
|
::
|
2020-10-30 03:46:16 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Series-links: 1:187331 2:188434 189372
|
2020-10-30 03:46:16 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Patman always uses the one without a version, since it assumes this is
|
|
|
|
the latest one. When this tag is provided, patman can compare your local
|
|
|
|
branch against patchwork to see what new reviews your series has
|
|
|
|
collected ('patman status').
|
2020-10-30 03:46:16 +00:00
|
|
|
|
2020-11-03 20:54:16 +00:00
|
|
|
Series-patchwork-url: url
|
2022-08-09 19:49:57 +00:00
|
|
|
This allows specifying the Patchwork URL for a branch. This overrides
|
|
|
|
both the setting files and the command-line argument. The URL should
|
|
|
|
include the protocol and web site, with no trailing slash, for example
|
|
|
|
'https://patchwork.ozlabs.org/project'
|
2020-11-03 20:54:16 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Cover-letter:
|
2022-08-09 19:49:57 +00:00
|
|
|
Sets the cover letter contents for the series. The first line
|
|
|
|
will become the subject of the cover letter::
|
|
|
|
|
|
|
|
Cover-letter:
|
|
|
|
This is the patch set title
|
|
|
|
blah blah
|
|
|
|
more blah blah
|
|
|
|
END
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2013-03-20 16:43:00 +00:00
|
|
|
Cover-letter-cc: email / alias
|
2022-08-09 19:49:57 +00:00
|
|
|
Additional email addresses / aliases to send cover letter to (you
|
|
|
|
can add this multiple times)
|
2013-03-20 16:43:00 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Series-notes:
|
2022-08-09 19:49:57 +00:00
|
|
|
Sets some notes for the patch series, which you don't want in
|
|
|
|
the commit messages, but do want to send, The notes are joined
|
|
|
|
together and put after the cover letter. Can appear multiple
|
|
|
|
times::
|
|
|
|
|
|
|
|
Series-notes:
|
|
|
|
blah blah
|
|
|
|
blah blah
|
|
|
|
more blah blah
|
|
|
|
END
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2013-11-12 10:14:41 +00:00
|
|
|
Commit-notes:
|
2022-08-09 19:49:57 +00:00
|
|
|
Similar, but for a single commit (patch). These notes will appear
|
2024-01-06 10:36:54 +00:00
|
|
|
immediately below the ``---`` cut in the patch file::
|
2022-08-09 19:49:57 +00:00
|
|
|
|
|
|
|
Commit-notes:
|
|
|
|
blah blah
|
|
|
|
blah blah
|
|
|
|
more blah blah
|
|
|
|
|
|
|
|
Signed-off-by: Their Name <email>
|
|
|
|
A sign-off is added automatically to your patches (this is
|
|
|
|
probably a bug). If you put this tag in your patches, it will
|
|
|
|
override the default signoff that patman automatically adds.
|
|
|
|
Multiple duplicate signoffs will be removed.
|
|
|
|
|
|
|
|
Tested-by / Reviewed-by / Acked-by
|
|
|
|
These indicate that someone has tested/reviewed/acked your patch.
|
|
|
|
When you get this reply on the mailing list, you can add this
|
|
|
|
tag to the relevant commit and the script will include it when
|
|
|
|
you send out the next version. If 'Tested-by:' is set to
|
|
|
|
yourself, it will be removed. No one will believe you.
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
Tested-by: Their Name <fred@bloggs.com>
|
|
|
|
Reviewed-by: Their Name <email>
|
|
|
|
Acked-by: Their Name <email>
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-changes: n
|
2022-08-09 19:49:57 +00:00
|
|
|
This can appear in any commit. It lists the changes for a
|
|
|
|
particular version n of that commit. The change list is
|
|
|
|
created based on this information. Each commit gets its own
|
|
|
|
change list and also the whole thing is repeated in the cover
|
|
|
|
letter (where duplicate change lines are merged).
|
|
|
|
|
|
|
|
By adding your change lists into your commits it is easier to
|
|
|
|
keep track of what happened. When you amend a commit, remember
|
|
|
|
to update the log there and then, knowing that the script will
|
|
|
|
do the rest.
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
Series-changes: n
|
|
|
|
- Guinea pig moved into its cage
|
|
|
|
- Other changes ending with a blank line
|
|
|
|
<blank line>
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2020-05-04 20:28:34 +00:00
|
|
|
Commit-changes: n
|
2022-08-09 19:49:57 +00:00
|
|
|
This tag is like Series-changes, except changes in this changelog will
|
|
|
|
only appear in the changelog of the commit this tag is in. This is
|
|
|
|
useful when you want to add notes which may not make sense in the cover
|
|
|
|
letter. For example, you can have short changes such as "New" or
|
|
|
|
"Lint".
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
Commit-changes: n
|
|
|
|
- This line will not appear in the cover-letter changelog
|
|
|
|
<blank line>
|
2020-05-04 20:28:34 +00:00
|
|
|
|
|
|
|
Cover-changes: n
|
2022-08-09 19:49:57 +00:00
|
|
|
This tag is like Series-changes, except changes in this changelog will
|
|
|
|
only appear in the cover-letter changelog. This is useful to summarize
|
|
|
|
changes made with Commit-changes, or to add additional context to
|
|
|
|
changes.
|
|
|
|
|
|
|
|
Example::
|
|
|
|
|
|
|
|
Cover-changes: n
|
|
|
|
- This line will only appear in the cover letter
|
|
|
|
<blank line>
|
2020-05-04 20:28:34 +00:00
|
|
|
|
2014-02-16 15:23:47 +00:00
|
|
|
Patch-cc: Their Name <email>
|
2022-08-09 19:49:57 +00:00
|
|
|
This copies a single patch to another email address. Note that the
|
|
|
|
Cc: used by git send-email is ignored by patman, but will be
|
|
|
|
interpreted by git send-email if you use it.
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2013-03-26 13:09:44 +00:00
|
|
|
Series-process-log: sort, uniq
|
2022-08-09 19:49:57 +00:00
|
|
|
This tells patman to sort and/or uniq the change logs. Changes may be
|
|
|
|
multiple lines long, as long as each subsequent line of a change begins
|
|
|
|
with a whitespace character. For example,
|
2020-05-04 20:28:35 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Example::
|
2020-05-04 20:28:35 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
- This change
|
|
|
|
continues onto the next line
|
|
|
|
- But this change is separate
|
|
|
|
|
|
|
|
Use 'sort' to sort the entries, and 'uniq' to include only
|
|
|
|
unique entries. If omitted, no change log processing is done.
|
|
|
|
Separate each tag with a comma.
|
2013-03-26 13:09:44 +00:00
|
|
|
|
2019-09-27 16:23:56 +00:00
|
|
|
Change-Id:
|
2023-10-13 03:06:24 +00:00
|
|
|
This tag is used to generate the Message-Id of the emails that
|
|
|
|
will be sent. When you keep the Change-Id the same you are
|
|
|
|
asserting that this is a slightly different version (but logically
|
|
|
|
the same patch) as other patches that have been sent out with the
|
|
|
|
same Change-Id. The Change-Id tag line is removed from outgoing
|
|
|
|
patches, unless the `keep_change_id` settings is set to `True`.
|
2019-09-27 16:23:56 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Various other tags are silently removed, like these Chrome OS and
|
2022-08-09 19:49:57 +00:00
|
|
|
Gerrit tags::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
BUG=...
|
|
|
|
TEST=...
|
|
|
|
Review URL:
|
|
|
|
Reviewed-on:
|
|
|
|
Commit-xxxx: (except Commit-notes)
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Exercise for the reader: Try adding some tags to one of your current
|
|
|
|
patch series and see how the patches turn out.
|
|
|
|
|
|
|
|
|
|
|
|
Where Patches Are Sent
|
2022-08-09 19:49:57 +00:00
|
|
|
----------------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2012-04-25 05:45:05 +00:00
|
|
|
Once the patches are created, patman sends them using git send-email. The
|
2012-01-14 15:12:45 +00:00
|
|
|
whole series is sent to the recipients in Series-to: and Series-cc.
|
2014-02-16 15:23:47 +00:00
|
|
|
You can Cc individual patches to other people with the Patch-cc: tag. Tags
|
|
|
|
in the subject are also picked up to Cc patches. For example, a commit like
|
2022-08-09 19:49:57 +00:00
|
|
|
this::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
commit 10212537b85ff9b6e09c82045127522c0f0db981
|
|
|
|
Author: Mike Frysinger <vapier@gentoo.org>
|
|
|
|
Date: Mon Nov 7 23:18:44 2011 -0500
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
x86: arm: add a git mailrc file for maintainers
|
|
|
|
|
|
|
|
This should make sending out e-mails to the right people easier.
|
|
|
|
|
2014-02-16 15:23:47 +00:00
|
|
|
Patch-cc: sandbox, mikef, ag
|
|
|
|
Patch-cc: afleming
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
will create a patch which is copied to x86, arm, sandbox, mikef, ag and
|
|
|
|
afleming.
|
|
|
|
|
2014-02-16 15:23:47 +00:00
|
|
|
If you have a cover letter it will get sent to the union of the Patch-cc
|
|
|
|
lists of all of the other patches. If you want to sent it to additional
|
2022-08-09 19:49:57 +00:00
|
|
|
people you can add a tag::
|
2013-03-20 16:43:00 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Cover-letter-cc: <list of addresses>
|
2013-03-20 16:43:00 +00:00
|
|
|
|
|
|
|
These people will get the cover letter even if they are not on the To/Cc
|
|
|
|
list for any of the patches.
|
2012-12-03 14:40:43 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2020-10-30 03:46:35 +00:00
|
|
|
Patchwork Integration
|
2022-08-09 19:49:57 +00:00
|
|
|
---------------------
|
2020-10-30 03:46:35 +00:00
|
|
|
|
|
|
|
Patman has a very basic integration with Patchwork. If you point patman to
|
2022-08-09 19:49:57 +00:00
|
|
|
your series on patchwork it can show you what new reviews have appeared since
|
2020-10-30 03:46:35 +00:00
|
|
|
you sent your series.
|
|
|
|
|
|
|
|
To set this up, add a Series-link tag to one of the commits in your series
|
|
|
|
(see above).
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Then you can type:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
2020-10-30 03:46:35 +00:00
|
|
|
|
|
|
|
patman status
|
|
|
|
|
|
|
|
and patman will show you each patch and what review tags have been collected,
|
2022-08-09 19:49:57 +00:00
|
|
|
for example::
|
2020-10-30 03:46:35 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
...
|
|
|
|
21 x86: mtrr: Update the command to use the new mtrr
|
|
|
|
Reviewed-by: Wolfgang Wallner <wolfgang.wallner@br-automation.com>
|
|
|
|
+ Reviewed-by: Bin Meng <bmeng.cn@gmail.com>
|
|
|
|
22 x86: mtrr: Restructure so command execution is in
|
|
|
|
Reviewed-by: Wolfgang Wallner <wolfgang.wallner@br-automation.com>
|
|
|
|
+ Reviewed-by: Bin Meng <bmeng.cn@gmail.com>
|
|
|
|
...
|
2020-10-30 03:46:35 +00:00
|
|
|
|
|
|
|
This shows that patch 21 and 22 were sent out with one review but have since
|
|
|
|
attracted another review each. If the series needs changes, you can update
|
|
|
|
these commits with the new review tag before sending the next version of the
|
|
|
|
series.
|
|
|
|
|
2020-10-30 03:46:36 +00:00
|
|
|
To automatically pull into these tags into a new branch, use the -d option:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2020-10-30 03:46:36 +00:00
|
|
|
patman status -d mtrr4
|
|
|
|
|
|
|
|
This will create a new 'mtrr4' branch which is the same as your current branch
|
|
|
|
but has the new review tags in it. The tags are added in alphabetic order and
|
|
|
|
are placed immediately after any existing ack/review/test/fixes tags, or at the
|
|
|
|
end. You can check that this worked with:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2020-10-30 03:46:36 +00:00
|
|
|
patman -b mtrr4 status
|
|
|
|
|
|
|
|
which should show that there are no new responses compared to this new branch.
|
|
|
|
|
2020-10-30 03:46:38 +00:00
|
|
|
There is also a -C option to list the comments received for each patch.
|
|
|
|
|
2020-10-30 03:46:35 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Example Work Flow
|
2022-08-09 19:49:57 +00:00
|
|
|
-----------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
The basic workflow is to create your commits, add some tags to the top
|
|
|
|
commit, and type 'patman' to check and send them.
|
|
|
|
|
|
|
|
Here is an example workflow for a series of 4 patches. Let's say you have
|
|
|
|
these rather contrived patches in the following order in branch us-cmd in
|
|
|
|
your tree where 'us' means your upstreaming activity (newest to oldest as
|
2022-08-09 19:49:57 +00:00
|
|
|
output by git log --oneline)::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
7c7909c wip
|
|
|
|
89234f5 Don't include standard parser if hush is used
|
|
|
|
8d640a7 mmc: sparc: Stop using builtin_run_command()
|
|
|
|
0c859a9 Rename run_command2() to run_command()
|
|
|
|
a74443f sandbox: Rename run_command() to builtin_run_command()
|
|
|
|
|
|
|
|
The first patch is some test things that enable your code to be compiled,
|
|
|
|
but that you don't want to submit because there is an existing patch for it
|
|
|
|
on the list. So you can tell patman to create and check some patches
|
|
|
|
(skipping the first patch) with:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2021-01-23 15:56:14 +00:00
|
|
|
patman -s1 send -n
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
If you want to do all of them including the work-in-progress one, then
|
|
|
|
(if you are tracking an upstream branch):
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2021-01-23 15:56:14 +00:00
|
|
|
patman send -n
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Let's say that patman reports an error in the second patch. Then:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
git rebase -i HEAD~6
|
2022-08-09 19:49:57 +00:00
|
|
|
# change 'pick' to 'edit' in 89234f5
|
|
|
|
# use editor to make code changes
|
2012-01-14 15:12:45 +00:00
|
|
|
git add -u
|
|
|
|
git rebase --continue
|
|
|
|
|
|
|
|
Now you have an updated patch series. To check it:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2021-01-23 15:56:14 +00:00
|
|
|
patman -s1 send -n
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Let's say it is now clean and you want to send it. Now you need to set up
|
|
|
|
the destination. So amend the top commit with:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
git commit --amend
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Use your editor to add some tags, so that the whole commit message is::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
The current run_command() is really only one of the options, with
|
|
|
|
hush providing the other. It really shouldn't be called directly
|
|
|
|
in case the hush parser is bring used, so rename this function to
|
2022-08-09 19:49:57 +00:00
|
|
|
better explain its purpose::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-to: u-boot
|
|
|
|
Series-cc: bfin, marex
|
|
|
|
Series-prefix: RFC
|
|
|
|
Cover-letter:
|
|
|
|
Unified command execution in one place
|
|
|
|
|
|
|
|
At present two parsers have similar code to execute commands. Also
|
|
|
|
cmd_usage() is called all over the place. This series adds a single
|
|
|
|
function which processes commands called cmd_process().
|
|
|
|
END
|
|
|
|
|
|
|
|
Change-Id: Ica71a14c1f0ecb5650f771a32fecb8d2eb9d8a17
|
|
|
|
|
|
|
|
|
|
|
|
You want this to be an RFC and Cc the whole series to the bfin alias and
|
|
|
|
to Marek. Two of the patches have tags (those are the bits at the front of
|
|
|
|
the subject that say mmc: sparc: and sandbox:), so 8d640a7 will be Cc'd to
|
|
|
|
mmc and sparc, and the last one to sandbox.
|
|
|
|
|
|
|
|
Now to send the patches, take off the -n flag:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2021-01-23 15:56:14 +00:00
|
|
|
patman -s1 send
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
The patches will be created, shown in your editor, and then sent along with
|
|
|
|
the cover letter. Note that patman's tags are automatically removed so that
|
|
|
|
people on the list don't see your secret info.
|
|
|
|
|
|
|
|
Of course patches often attract comments and you need to make some updates.
|
|
|
|
Let's say one person sent comments and you get an Acked-by: on one patch.
|
|
|
|
Also, the patch on the list that you were waiting for has been merged,
|
2020-10-30 03:46:38 +00:00
|
|
|
so you can drop your wip commit.
|
|
|
|
|
|
|
|
Take a look on patchwork and find out the URL of the series. This will be
|
2022-08-09 19:49:57 +00:00
|
|
|
something like `http://patchwork.ozlabs.org/project/uboot/list/?series=187331`
|
|
|
|
Add this to a tag in your top commit::
|
2020-10-30 03:46:38 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Series-links: 187331
|
2020-10-30 03:46:38 +00:00
|
|
|
|
|
|
|
You can use then patman to collect the Acked-by tag to the correct commit,
|
|
|
|
creating a new 'version 2' branch for us-cmd:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2020-10-30 03:46:38 +00:00
|
|
|
patman status -d us-cmd2
|
|
|
|
git checkout us-cmd2
|
|
|
|
|
|
|
|
You can look at the comments in Patchwork or with:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2020-10-30 03:46:38 +00:00
|
|
|
patman status -C
|
|
|
|
|
|
|
|
Then you can resync with upstream:
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
git fetch origin # or whatever upstream is called
|
2012-01-14 15:12:45 +00:00
|
|
|
git rebase origin/master
|
|
|
|
|
2020-10-30 03:46:38 +00:00
|
|
|
and use git rebase -i to edit the commits, dropping the wip one.
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Then update the `Series-cc:` in the top commit to add the person who reviewed
|
|
|
|
the v1 series::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-cc: bfin, marex, Heiko Schocher <hs@denx.de>
|
|
|
|
|
|
|
|
and remove the Series-prefix: tag since it it isn't an RFC any more. The
|
|
|
|
series is now version two, so the series info in the top commit looks like
|
2022-08-09 19:49:57 +00:00
|
|
|
this::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-to: u-boot
|
|
|
|
Series-cc: bfin, marex, Heiko Schocher <hs@denx.de>
|
|
|
|
Series-version: 2
|
|
|
|
Cover-letter:
|
|
|
|
...
|
|
|
|
|
|
|
|
Finally, you need to add a change log to the two commits you changed. You
|
|
|
|
add change logs to each individual commit where the changes happened, like
|
2022-08-09 19:49:57 +00:00
|
|
|
this::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
Series-changes: 2
|
|
|
|
- Updated the command decoder to reduce code size
|
|
|
|
- Wound the torque propounder up a little more
|
|
|
|
|
|
|
|
(note the blank line at the end of the list)
|
|
|
|
|
|
|
|
When you run patman it will collect all the change logs from the different
|
|
|
|
commits and combine them into the cover letter, if you have one. So finally
|
2022-08-09 19:49:57 +00:00
|
|
|
you have a new series of commits::
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
faeb973 Don't include standard parser if hush is used
|
|
|
|
1b2f2fe mmc: sparc: Stop using builtin_run_command()
|
|
|
|
cfbe330 Rename run_command2() to run_command()
|
|
|
|
0682677 sandbox: Rename run_command() to builtin_run_command()
|
|
|
|
|
|
|
|
so to send them:
|
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
patman
|
|
|
|
|
|
|
|
and it will create and send the version 2 series.
|
|
|
|
|
2020-10-30 03:46:38 +00:00
|
|
|
|
|
|
|
General points
|
2022-08-09 19:49:57 +00:00
|
|
|
--------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
#. When you change back to the us-cmd branch days or weeks later all your
|
2022-08-09 19:49:57 +00:00
|
|
|
information is still there, safely stored in the commits. You don't need
|
|
|
|
to remember what version you are up to, who you sent the last lot of patches
|
|
|
|
to, or anything about the change logs.
|
2022-08-17 18:47:07 +00:00
|
|
|
#. If you put tags in the subject, patman will Cc the maintainers
|
2022-08-09 19:49:57 +00:00
|
|
|
automatically in many cases.
|
2022-08-17 18:47:07 +00:00
|
|
|
#. If you want to keep the commits from each series you sent so that you can
|
2022-08-09 19:49:57 +00:00
|
|
|
compare change and see what you did, you can either create a new branch for
|
|
|
|
each version, or just tag the branch before you start changing it:
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
.. code-block:: bash
|
2022-08-09 19:49:57 +00:00
|
|
|
|
|
|
|
git tag sent/us-cmd-rfc
|
|
|
|
# ...later...
|
|
|
|
git tag sent/us-cmd-v2
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
#. If you want to modify the patches a little before sending, you can do
|
2022-08-09 19:49:57 +00:00
|
|
|
this in your editor, but be careful!
|
2022-08-17 18:47:07 +00:00
|
|
|
#. If you want to run git send-email yourself, use the -n flag which will
|
2022-08-09 19:49:57 +00:00
|
|
|
print out the command line patman would have used.
|
2022-08-17 18:47:07 +00:00
|
|
|
#. It is a good idea to add the change log info as you change the commit,
|
2022-08-09 19:49:57 +00:00
|
|
|
not later when you can't remember which patch you changed. You can always
|
|
|
|
go back and change or remove logs from commits.
|
2022-08-17 18:47:07 +00:00
|
|
|
#. Some mailing lists have size limits and when we add binary contents to
|
2022-08-09 19:49:57 +00:00
|
|
|
our patches it's easy to exceed the size limits. Use "--no-binary" to
|
|
|
|
generate patches without any binary contents. You are supposed to include
|
|
|
|
a link to a git repository in your "Commit-notes", "Series-notes" or
|
|
|
|
"Cover-letter" for maintainers to fetch the original commit.
|
2022-08-17 18:47:07 +00:00
|
|
|
#. Patches will have no changelog entries for revisions where they did not
|
2022-08-09 19:49:57 +00:00
|
|
|
change. For clarity, if there are no changes for this patch in the most
|
|
|
|
recent revision of the series, a note will be added. For example, a patch
|
|
|
|
with the following tags in the commit::
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Series-version: 5
|
|
|
|
Series-changes: 2
|
|
|
|
- Some change
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
Series-changes: 4
|
|
|
|
- Another change
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
would have a changelog of:::
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
(no changes since v4)
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
Changes in v4:
|
|
|
|
- Another change
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-17 18:47:07 +00:00
|
|
|
Changes in v2:
|
|
|
|
- Some change
|
2020-05-04 20:28:33 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Other thoughts
|
2022-08-09 19:49:57 +00:00
|
|
|
--------------
|
2012-01-14 15:12:45 +00:00
|
|
|
|
|
|
|
This script has been split into sensible files but still needs work.
|
|
|
|
Most of these are indicated by a TODO in the code.
|
|
|
|
|
|
|
|
It would be nice if this could handle the In-reply-to side of things.
|
|
|
|
|
2020-10-30 03:46:12 +00:00
|
|
|
The tests are incomplete, as is customary. Use the 'test' subcommand to run
|
|
|
|
them:
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-08-09 19:49:57 +00:00
|
|
|
.. code-block:: bash
|
|
|
|
|
2020-10-30 03:46:12 +00:00
|
|
|
$ tools/patman/patman test
|
2012-01-14 15:12:45 +00:00
|
|
|
|
2022-12-19 22:32:43 +00:00
|
|
|
Note that since the test suite depends on data files only available in
|
|
|
|
the git checkout, the `test` command is hidden unless `patman` is
|
|
|
|
invoked from the U-Boot git repository.
|
|
|
|
|
2022-12-19 22:32:44 +00:00
|
|
|
Alternatively, you can run the test suite via Pytest:
|
|
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
|
|
|
|
$ cd tools/patman && pytest
|
|
|
|
|
2012-01-14 15:12:45 +00:00
|
|
|
Error handling doesn't always produce friendly error messages - e.g.
|
|
|
|
putting an incorrect tag in a commit may provide a confusing message.
|
|
|
|
|
|
|
|
There might be a few other features not mentioned in this README. They
|
|
|
|
might be bugs. In particular, tags are case sensitive which is probably
|
|
|
|
a bad thing.
|