[PATCH 5/9] patman: Replace the documentation with a stub
Simon Glass
sjg at chromium.org
Tue Jun 16 16:28:45 CEST 2026
The full patman manual now lives with the standalone patch-manager
package, making the 1000-line copy in the tree redundant. Its published
page is a long-standing URL, though, so removing it outright would break
existing links.
Replace the in-tree manual with a short stub that points readers at the
patch-manager package, and keep the toctree entry so the page still
builds. Drop the README and the tool's own rst, and point the
patch-sending docs at the standalone package too.
Signed-off-by: Simon Glass <sjg at chromium.org>
---
doc/develop/driver-model/spi-howto.rst | 5 +-
doc/develop/patman.rst | 15 +-
doc/develop/sending_patches.rst | 4 +-
tools/patman/README.rst | 1 -
tools/patman/patman.rst | 1023 ------------------------
5 files changed, 20 insertions(+), 1028 deletions(-)
mode change 120000 => 100644 doc/develop/patman.rst
delete mode 120000 tools/patman/README.rst
delete mode 100644 tools/patman/patman.rst
diff --git a/doc/develop/driver-model/spi-howto.rst b/doc/develop/driver-model/spi-howto.rst
index 9dc3b9b4aac..c5b07ba0e47 100644
--- a/doc/develop/driver-model/spi-howto.rst
+++ b/doc/develop/driver-model/spi-howto.rst
@@ -649,8 +649,9 @@ board.
Prepare patches and send them to the mailing lists
--------------------------------------------------
-You can use 'tools/patman/patman' to prepare, check and send patches for
-your work. See tools/patman/README for details.
+You can use the patman tool to prepare, check and send patches for your work.
+Install it with ``pip install patch-manager``; see the
+`patman documentation <https://deinde.dev/patman>`_.
A little note about SPI uclass features
---------------------------------------
diff --git a/doc/develop/patman.rst b/doc/develop/patman.rst
deleted file mode 120000
index 0fcb7d61d40..00000000000
--- a/doc/develop/patman.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../tools/patman/patman.rst
\ No newline at end of file
diff --git a/doc/develop/patman.rst b/doc/develop/patman.rst
new file mode 100644
index 00000000000..58b439cf0fb
--- /dev/null
+++ b/doc/develop/patman.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+patman
+======
+
+patman is no longer part of the U-Boot tree. It is now maintained as a
+separate package called 'patch-manager'.
+
+Install it with::
+
+ pip install patch-manager
+
+See the `patman documentation <https://deinde.dev/patman>`_ for more
+information.
diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index e29fa175727..d084e360681 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -24,7 +24,9 @@ You can use a tool called patman to prepare, check and send patches. It creates
change logs, cover letters and patch notes. It also simplifies the process of
sending multiple versions of a series.
-See more details at :doc:`patman`.
+patman now lives outside the U-Boot tree; install it with
+``pip install patch-manager``. See the
+`patman documentation <https://deinde.dev/patman>`_ for details.
General Patch Submission Rules
------------------------------
diff --git a/tools/patman/README.rst b/tools/patman/README.rst
deleted file mode 120000
index 76368b95980..00000000000
--- a/tools/patman/README.rst
+++ /dev/null
@@ -1 +0,0 @@
-patman.rst
\ No newline at end of file
diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst
deleted file mode 100644
index 549e203c254..00000000000
--- a/tools/patman/patman.rst
+++ /dev/null
@@ -1,1023 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-.. Copyright (c) 2011 The Chromium OS Authors
-.. Simon Glass <sjg at chromium.org>
-.. Maxim Cournoyer <maxim.cournoyer at savoirfairelinux.com>
-.. v1, v2, 19-Oct-11
-.. revised v3 24-Nov-11
-.. revised v4 Independence Day 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
-- Links the series automatically to Patchwork once sent
-
-It also has some Patchwork features:
-
-- Manage local series and their status on patchwork
-- Show review tags from Patchwork and allows them to be gathered into commits
-- List 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 at 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).
-
-
-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`.
-
-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. 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.
-
-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 at chromium.org>
-
- u-boot: U-Boot Mailing List <u-boot at lists.denx.de>
- wolfgang: Wolfgang Denk <wd at denx.de>
- others: Mike Frysinger <vapier at gentoo.org>, Fred Bloggs <f.bloggs at napier.net>
-
-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.
-
-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 at 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_url: 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 ("patchwork_url") 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 at 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>
-
-Commit-added-in: n
- Add a change noting the version this commit was added in. This is
- equivalent to::
-
- Commit-changes: n
- - New
-
- Cover-changes: n
- - <commit subject>
-
- It is a convenient shorthand for suppressing the '(no changes in vN)'
- message.
-
-Patch-cc / Commit-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 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`.
-
-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 at 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 at br-automation.com>
- + Reviewed-by: Bin Meng <bmeng.cn at gmail.com>
- 22 x86: mtrr: Restructure so command execution is in
- Reviewed-by: Wolfgang Wallner <wolfgang.wallner at br-automation.com>
- + Reviewed-by: Bin Meng <bmeng.cn at 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 at 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 at 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.
-
-
-Series Management
------------------
-
-Sometimes you might have several series in flight at the same time. Each of
-these receives comments and you want to create a new version of each series with
-those comments addressed.
-
-Patman provides a few subcommands which are helpful for managing series.
-
-Series and branches
-~~~~~~~~~~~~~~~~~~~
-
-'patman series' works with the concept of a series. It maintains a local
-database (.patman.db in your top-level git tree) and uses that to keep track of
-series and patches.
-
-Each series goes through muliple versions. Patman requires that the first
-version of your series is in a branch without a numeric suffix. Branch names
-like 'serial' and 'video' are OK, but 'part3' is not. This is because Patman
-uses the number at the end of the branch name to indicate the version.
-
-If your series name is 'video', then you can have a 'video' branch for version
-1 of the series, 'video2' for version 2 and 'video3' for version 3. All three
-branches are for the same series. Patman keeps track of these different
-versions. It handles the branch naming automatically, but you need to be aware
-of what it is doing.
-
-You will have an easier time if the branch names you use with 'patman series'
-are short, no more than 15 characters. This is the amount of columnar space in
-listings. You can add a longer description as the series description. If you
-are used to having very descriptive branch names, remember that patman lets you
-add metadata into commit which is automatically removed before sending.
-
-This documentation uses the term 'series' to mean all the versions of a series
-and 'series/version' to mean a particular version of a series.
-
-Updating commits
-~~~~~~~~~~~~~~~~
-
-Since Patman provides quite a bit of automation, it updates your commits in
-some cases, effectively doing a rebase of a branch in order to change the tags
-in the commits. It never makes code changes.
-
-In extremis you can use 'git reflog' to revert something that Patman did.
-
-
-Series subcommands
-~~~~~~~~~~~~~~~~~~
-
-Note that 'patman series ...' can be abbreviated as 'patman s' or 'patman ser'.
-
-Here is a short overview of the available subcommands:
-
- add
- Add a new series. Use this on an existing branch to tell Patman about it.
-
- archive (ar)
- Archive a series when you have finished upstreaming it. Archived series
- are not shown by most commands. This creates a dated tag for each
- version of the series, pointing to the series branch, then deletes the
- branches. It puts the tag names in the database so that it can
- 'unarchive' to restore things how they were.
-
- unarchive (unar)
- Unarchive a series when you decide you need to do something more with
- it. The branches are restored and tags deleted.
-
- autolink (au)
- Search patchwork for the series link for your series, so Patman can
- track the status
-
- autolink-all
- Same but for all series
-
- inc
- Increase the series number, effectively creating a new branch with the
- next highest version number. The new branch is created based on the
- existing branch. So if you use 'patman series inc' on branch 'video2'
- it will create branch 'video3' and add v3 into its database
-
- dec
- Decrease the series number, thus deleting the current branch and
- removing that version from the data. If you use this comment on branch
- 'video3' Patman will delete version 3 and branch 'video3'.
-
- get-link
- Shows the Patchwork link for a series/version
-
- ls
- Lists the series in the database
-
- mark
- Mark a series with 'Change-Id' tags so that Patman can track patches
- even when the subject changes. Unmarked patches just use the subject to
- decided which is which.
-
- unmark
- Remove 'Change-Id' tags from a series.
-
- open (o)
- Open a series in Patchwork using your web browser
-
- patches
- Show the patches in a particular series/version
-
- progress (p)
- Show upstream progress for your series, or for all series
-
- rm
- Remove a series entirely, including all versions
-
- rm-version (rmv)
- Remove a particular version of a series. This is similar to 'dec'
- except that any version can be removed, not just the latest one.
-
- scan
- Scan the local branch and update the database with the set of patches
- in that branch. This throws away the old patches.
-
- send
- Send a series out as patches. This is similar to 'patman send' except
- that it can send any series, not just the current branch. It also
- waits a little for patchwork to see the cover letter, so it can find
- out the patchwork link for the series.
-
- set-link
- Sets the Patchwork link for a series-version manually.
-
- status (st)
- Run 'patman status' on a series. This is similar to 'patman status'
- except that it can get status on any series, not just the current
- branch
-
- summary
- Shows a quick summary of series with their status and description.
-
- sync
- Sync the status of a series with Pathwork, so that
- 'patman series progress' can show the right information.
-
- sync-all
- Sync the status of all series.
-
-
-Patman series workflow
-~~~~~~~~~~~~~~~~~~~~~~
-
-Here is a run-through of how to incorporate 'patman series' into your workflow.
-
-Firstly, set up your project::
-
- patman patchwork set-project U-Boot
-
-This just tells Patman to look on the Patchwork server for a project of that
-name. Internally Patman stores the ID and URL 'link-name' for the project, so it
-can access it.
-
-If you need to use a different patchwork server, use the `--patchwork-url`
-option or put the URL in your Patman-settings file.
-
-Now create a branch. For our example we are going to send out a series related
-to video so the branch will be called 'video'. The upstream remove is called
-'us'::
-
- git checkout -b video us/master
-
-We now have a branch and so we can do some commits::
-
- <edit files>
- git add ...
- <edit files>
- git add -u
- git commit ...
- git commit ...
-
-We now have a few commits in our 'video' branch. Let's tell patman about it::
-
- patman series add
-
-Like most commands, if no series is given (`patman series -s video add`) then
-the current branch is assumed. Since the branch is called 'video' patman knows
-that it is version one of the video series.
-
-You'll likely get a warning that there is no cover letter. Let's add some tags
-to the top commit::
-
- Series-to: u-boot
- Series-cc: ...
- Cover-letter:
- video: Improve syncing performance with cyclic
-
-Trying again::
-
- patman series add
-
-You'll likely get a warning that the commits are unmarked. You can either let
-patman add Change-Id values itself with the `-m` flag, or tell it not to worry
-about it with `-M`. You must choose one or the other. Let's leave the commits
-unmarked::
-
- patman series add -M
-
-Congratulations, you've now got a patman database!
-
-Now let's send out the series. We will add tags to the top commit.
-
-To send it::
-
- patman series send
-
-You should send 'git send-email' start up and you can confirm the sending of
-each email.
-
-After that, patman waits a bit to see if it can find your new series appearing
-on Patchwork. With a bit of luck this will only take 20 seconds or so. Then your
-series is linked.
-
-To gather tags (Reviewed-by ...) for your series from patchwork::
-
- patman series gather
-
-Now you can check your progress::
-
- patman series progress
-
-Later on you get some comments, or perhaps you just decide to make a change on
-your own. You have several options.
-
-The first option is that you can just create a new branch::
-
- git checkout -b video2 video
-
-then you can add this 'v2' series to Patman with::
-
- patman series add
-
-The second option is to get patman to create the new 'video2' branch in one
-step::
-
- patman inc
-
-The third option is to collect some tags using the 'patman status' command and
-put them in a new branch::
-
- patman status -d video2
-
-One day the fourth option will be to ask patman to collect tags as part of the
-'patman inc' command.
-
-Again, you do your edits, perhaps adding/removing patches, rebasing on -master
-and so on. Then, send your v2::
-
- patman series send
-
-Let's say the patches are accepted. You can use::
-
- patch series gather
- patch series progress
-
-to check, or::
-
- patman series status -cC
-
-to see comments. You can now archive the series::
-
- patman series archive
-
-At this point you have the basics. Some of the subcommands useful options, so
-be sure to check out the help.
-
-Here is a sample 'progress' view:
-
-.. image:: pics/patman.jpg
- :width: 800
- :alt: Patman showing the progress view
-
-General points
---------------
-
-#. 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.
-#. If you put tags in the subject, patman will Cc the maintainers
- automatically in many cases.
-#. 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
-
-#. If you want to modify the patches a little before sending, you can do
- this in your editor, but be careful!
-#. If you want to run git send-email yourself, use the -n flag which will
- print out the command line patman would have used.
-#. 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.
-#. 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.
-#. 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
-
-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.
-
-Alternatively, you can run the test suite via Pytest:
-
-.. code-block:: bash
-
- $ cd tools/patman && pytest
-
-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.
--
2.43.0
More information about the U-Boot
mailing list