patch-manager 0.0.5__tar.gz → 0.0.7__tar.gz

{patch-manager-0.0.5 → patch_manager-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: patch-manager
-Version: 0.0.5
+Version: 0.0.7
 Summary: Patman patch manager
 Author-email: Simon Glass <sjg@chromium.org>
 Project-URL: Homepage, https://docs.u-boot.org/en/latest/develop/patman.html
@@ -11,7 +11,9 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: u_boot_pylib>=0.0.5
+Requires-Dist: u_boot_pylib>=0.0.6
+Requires-Dist: aiohttp>=3.9.1
+Dynamic: license-file
 
 .. SPDX-License-Identifier: GPL-2.0+
 .. Copyright (c) 2011 The Chromium OS Authors
@@ -31,12 +33,13 @@ This tool is a Python script which:
 - 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:
 
-- 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
+- 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,
@@ -159,7 +162,7 @@ patman.py.  For reference, the useful ones (at the moment) shown below
     process_tags: False
     verbose: True
     smtp_server: /path/to/sendmail
-    patchwork_server: https://patchwork.ozlabs.org
+    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
@@ -263,9 +266,9 @@ Series-links: [id | version:id]...
 
 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'
+    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
@@ -295,7 +298,7 @@ Series-notes:
 
 Commit-notes:
     Similar, but for a single commit (patch). These notes will appear
-    immediately below the --- cut in the patch file::
+    immediately below the ``---`` cut in the patch file::
 
         Commit-notes:
         blah blah
@@ -365,7 +368,20 @@ Cover-changes: n
         - This line will only appear in the cover letter
         <blank line>
 
-Patch-cc: Their Name <email>
+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.
@@ -661,6 +677,282 @@ so to send them:
 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
 --------------