On Tue, 16 Jun 2026 at 15:39, Simon Glass <[email protected]> wrote: > > 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 <[email protected]> > --- > > 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>`_.
So this URL seems weird, and it redirects to https://patman.readthedocs.io/en/latest/ If I search for patch-manager on pypi.org the project goes to https://github.com/nxtboot/patman May I suggest that deinde.dev and nxtboot and patman and patch-manager as different names all feel disconnected, maybe some consistency around patman for the URLs, even if the github project is nxtboot, may provide less confusion for the users. > 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 <[email protected]> > -.. Maxim Cournoyer <[email protected]> > -.. 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: [email protected] > - > -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 <[email protected]> > - > - u-boot: U-Boot Mailing List <[email protected]> > - wolfgang: Wolfgang Denk <[email protected]> > - others: Mike Frysinger <[email protected]>, Fred Bloggs > <[email protected]> > - > -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 <[email protected]> > - > - > -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 <[email protected]> > - 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 <[email protected]> > - 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 <[email protected]> > - + Reviewed-by: Bin Meng <[email protected]> > - 22 x86: mtrr: Restructure so command execution is in > - Reviewed-by: Wolfgang Wallner <[email protected]> > - + Reviewed-by: Bin Meng <[email protected]> > - ... > - > -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 <[email protected]> > - > -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 <[email protected]> > - 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 >
