patman: Add documentation to doc/

Link to patman's documentation from the doc/ directory so that it appears
in the 'make htmldocs' output.

Signed-off-by: Simon Glass <sjg@chromium.org>
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>

1 files changed, 703 insertions, 0 deletions

diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst
new file mode 100644
index 0000000000..9226b66f84
--- /dev/null
+++ b/tools/patman/patman.rst
@@ -0,0 +1,703 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2011 The Chromium OS Authors
+.. Simon Glass <sjg@chromium.org>
+.. v1, v2, 19-Oct-11
+.. revised v3 24-Nov-11
+.. revised v4 04-Jul-2020, with Patchwork integration
+
+Patman patch manager
+====================
+
+This tool is a Python script which:
+
+- 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
+
+It also has some Patchwork features:
+
+- shows review tags from Patchwork so you can update your local patches
+
+- pulls these down into a new branch on request
+
+- lists comments received on a series
+
+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,
+since they use the checkpatch.pl script.
+
+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
+each time. So for example if you put::
+
+    Series-to: fred.blogs@napier.co.nz
+
+in one of your commits, the series will be sent there.
+
+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).
+
+
+How to use this tool
+--------------------
+
+This tool requires a certain way of working:
+
+- Maintain a number of branches, one for each patch series you are
+  working on
+
+- Add tags into the commits within each branch to indicate where the
+  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'
+
+- Each branch tracks the upstream branch, so that this script can
+  automatically determine the number of commits in it (optional)
+
+- Check out a branch, and run this script to create and send out your
+  patches. Weeks later, change the patches and repeat, knowing that you
+  will get a consistent result each time.
+
+
+How to configure it
+-------------------
+
+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
+this once::
+
+    git config sendemail.aliasesfile doc/git-mailrc
+
+For both Linux and U-Boot the 'scripts/get_maintainer.pl' handles figuring
+out where to send patches pretty well.
+
+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.
+
+To add your own, create a file ~/.patman like this::
+
+    # patman alias file
+
+    [alias]
+    me: Simon Glass <sjg@chromium.org>
+
+    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>
+
+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
+
+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
+that are not recursive::
+
+    [bounces]
+    gonefishing: Fred Bloggs <f.bloggs@napier.net>
+
+
+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
+(all with the non-default setting)::
+
+    [settings]
+    ignore_errors: True
+    process_tags: False
+    verbose: True
+    smtp_server: /path/to/sendmail
+    patchwork_server: https://patchwork.ozlabs.org
+
+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
+[project_alias].  If you want to use tags for your linux work, you could do::
+
+    [linux_settings]
+    process_tags: True
+
+
+How to run it
+-------------
+
+First do a dry run:
+
+.. code-block:: bash
+
+    ./tools/patman/patman send -n
+
+If it can't detect the upstream branch, try telling it how many patches
+there are in your series
+
+.. code-block:: bash
+
+    ./tools/patman/patman -c5 send -n
+
+This will create patch files in your current directory and tell you who
+it is thinking of sending them to. Take a look at the patch files:
+
+.. code-block:: bash
+
+    ./tools/patman/patman -c5 -s1 send -n
+
+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.
+
+
+How to install it
+-----------------
+
+The most up to date version of patman can be found in the U-Boot sources.
+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:
+
+.. code-block:: bash
+
+    cd tools/patman && python setup.py install
+
+
+How to add tags
+---------------
+
+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
+    Email address / alias to send patch series to (you can add this
+    multiple times)
+
+Series-cc: email / alias, ...
+    Email address / alias to Cc patch series to (you can add this
+    multiple times)
+
+Series-version: n
+    Sets the version number of this patch series
+
+Series-prefix: prefix
+    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]
+
+Series-postfix: postfix
+    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].
+
+Series-name: name
+    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.
+
+Series-links: [id | version:id]...
+    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.
+
+    ::
+
+       Series-links: 1:187331 2:188434 189372
+
+    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').
+
+Series-patchwork-url: url
+    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'
+
+Cover-letter:
+    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
+
+Cover-letter-cc: email / alias
+    Additional email addresses / aliases to send cover letter to (you
+    can add this multiple times)
+
+Series-notes:
+    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
+
+Commit-notes:
+    Similar, but for a single commit (patch). These notes will appear
+    immediately below the --- cut in the patch file::
+
+        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>
+
+Series-changes: n
+    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>
+
+Commit-changes: n
+    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>
+
+Cover-changes: n
+    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>
+
+Patch-cc: Their Name <email>
+    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.
+
+Series-process-log: sort, uniq
+    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,
+
+    Example::
+
+        - 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.
+
+Change-Id:
+    This tag is stripped out but 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.
+
+Various other tags are silently removed, like these Chrome OS and
+Gerrit tags::
+
+    BUG=...
+    TEST=...
+    Review URL:
+    Reviewed-on:
+    Commit-xxxx: (except Commit-notes)
+
+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
+----------------------
+
+Once the patches are created, patman sends them using git send-email. The
+whole series is sent to the recipients in Series-to: and Series-cc.
+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
+this::
+
+    commit 10212537b85ff9b6e09c82045127522c0f0db981
+    Author: Mike Frysinger <vapier@gentoo.org>
+    Date:    Mon Nov 7 23:18:44 2011 -0500
+
+    x86: arm: add a git mailrc file for maintainers
+
+    This should make sending out e-mails to the right people easier.
+
+    Patch-cc: sandbox, mikef, ag
+    Patch-cc: afleming
+
+will create a patch which is copied to x86, arm, sandbox, mikef, ag and
+afleming.
+
+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
+people you can add a tag::
+
+    Cover-letter-cc: <list of addresses>
+
+These people will get the cover letter even if they are not on the To/Cc
+list for any of the patches.
+
+
+Patchwork Integration
+---------------------
+
+Patman has a very basic integration with Patchwork. If you point patman to
+your series on patchwork it can show you what new reviews have appeared since
+you sent your series.
+
+To set this up, add a Series-link tag to one of the commits in your series
+(see above).
+
+Then you can type:
+
+.. code-block:: bash
+
+    patman status
+
+and patman will show you each patch and what review tags have been collected,
+for example::
+
+    ...
+     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>
+    ...
+
+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.
+
+To automatically pull into these tags into a new branch, use the -d option:
+
+.. code-block:: bash
+
+    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:
+
+.. code-block:: bash
+
+    patman -b mtrr4 status
+
+which should show that there are no new responses compared to this new branch.
+
+There is also a -C option to list the comments received for each patch.
+
+
+Example Work Flow
+-----------------
+
+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
+output by git log --oneline)::
+
+    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:
+
+.. code-block:: bash
+
+    patman -s1 send -n
+
+If you want to do all of them including the work-in-progress one, then
+(if you are tracking an upstream branch):
+
+.. code-block:: bash
+
+    patman send -n
+
+Let's say that patman reports an error in the second patch. Then:
+
+.. code-block:: bash
+
+    git rebase -i HEAD~6
+    # change 'pick' to 'edit' in 89234f5
+    # use editor to make code changes
+    git add -u
+    git rebase --continue
+
+Now you have an updated patch series. To check it:
+
+.. code-block:: bash
+
+    patman -s1 send -n
+
+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:
+
+.. code-block:: bash
+
+    git commit --amend
+
+Use your editor to add some tags, so that the whole commit message is::
+
+    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
+    better explain its purpose::
+
+    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:
+
+.. code-block:: bash
+
+   patman -s1 send
+
+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,
+so you can drop your wip commit.
+
+Take a look on patchwork and find out the URL of the series. This will be
+something like `http://patchwork.ozlabs.org/project/uboot/list/?series=187331`
+Add this to a tag in your top commit::
+
+   Series-links: 187331
+
+You can use then patman to collect the Acked-by tag to the correct commit,
+creating a new 'version 2' branch for us-cmd:
+
+.. code-block:: bash
+
+    patman status -d us-cmd2
+    git checkout us-cmd2
+
+You can look at the comments in Patchwork or with:
+
+.. code-block:: bash
+
+    patman status -C
+
+Then you can resync with upstream:
+
+.. code-block:: bash
+
+    git fetch origin        # or whatever upstream is called
+    git rebase origin/master
+
+and use git rebase -i to edit the commits, dropping the wip one.
+
+Then update the `Series-cc:` in the top commit to add the person who reviewed
+the v1 series::
+
+    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
+this::
+
+    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
+this::
+
+    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
+you have a new series of commits::
+
+    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:
+
+.. code-block:: bash
+
+    patman
+
+and it will create and send the version 2 series.
+
+
+General points
+--------------
+
+1. When you change back to the us-cmd branch days or weeks later all your
+   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.
+
+2. If you put tags in the subject, patman will Cc the maintainers
+   automatically in many cases.
+
+3. If you want to keep the commits from each series you sent so that you can
+   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:
+
+.. code-block:: bash
+
+        git tag sent/us-cmd-rfc
+        # ...later...
+        git tag sent/us-cmd-v2
+
+4. If you want to modify the patches a little before sending, you can do
+   this in your editor, but be careful!
+
+5. If you want to run git send-email yourself, use the -n flag which will
+   print out the command line patman would have used.
+
+6. It is a good idea to add the change log info as you change the commit,
+   not later when you can't remember which patch you changed. You can always
+   go back and change or remove logs from commits.
+
+7. Some mailing lists have size limits and when we add binary contents to
+   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.
+
+8. Patches will have no changelog entries for revisions where they did not
+   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::
+
+        Series-version: 5
+        Series-changes: 2
+        - Some change
+
+        Series-changes: 4
+        - Another change
+
+would have a changelog of:::
+
+    (no changes since v4)
+
+    Changes in v4:
+    - Another change
+
+    Changes in v2:
+    - Some change
+
+
+Other thoughts
+--------------
+
+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.
+
+The tests are incomplete, as is customary. Use the 'test' subcommand to run
+them:
+
+.. code-block:: bash
+
+    $ tools/patman/patman test
+
+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.