Streamlining Your Patch Workflow with Patman Series Management

Managing patch series can be one of the most time-consuming aspects of contributing to large open-source projects like U-Boot and Linux. While patman has long been a powerful tool for creating, checking, and sending patches, the relatively new patman series feature takes workflow management to the next level by providing lifecycle management for series, with Patchwork integration.

What is ‘patman series’?

The patman series feature (available via patman s or patman ser for brevity) is a database-backed, series-management system that tracks your patch series from initial creation through upstream acceptance. Unlike traditional patch workflows where you manually track versions, reviews, and status across multiple tools, patman series provides a unified interface that integrates directly with Patchwork to automate much of this tedious bookkeeping.

Key Benefits

Automated Series Tracking: Once you add a series to patman’s database, it automatically tracks versions, maintains links to Patchwork, and monitors upstream progress.

Seamless Version Management: Creating v2, v3, etc. of your series is as simple as patman series inc, which automatically creates new branches and updates the database.

Patchwork Integration: Patman automatically discovers your series on Patchwork after sending, tracks review comments, and can gather review tags back into your commits.

Branch Organization: The system encourages a clean branching strategy where each series version gets its own branch, making it easy to maintain multiple versions simultaneously.

Getting Started: A Complete Workflow

Let’s walk through a typical workflow using patman series. First, set up your project (this only needs to be done once):

patman patchwork set-project U-Boot

Now suppose you have a branch video2 with some patches ready to send. Add it to patman’s tracking:

git checkout video2
patman series add

Patman will scan your branch and add it to the database. You might see a warning about unmarked commits – you can either let patman add Change-Id values with -m or tell it not to worry with -M:

patman series add -M

Now send your series:

patman series send

Patman will use git send-email to send your patches and then wait to see if it can automatically find your series on Patchwork. Once linked, you can track its progress. In fact you can see the progress of all your series. Here is an example:

$ patman series progress
Name             Description                               Count  Status
---------------  ----------------------------------------  -----  ---------------
apa              lib: Split fdt_print() into separate libr     4  4:unknown
apb              efi: App and devicetree improvements         20 *20:unknown
app-us           efi_loader: Separate device path into its     3  3:accepted
appc             [00/27] x86: efi: Various app improvement    27  27:n/a
appd             doc: efi_loader: Tidy up the bootefi-comm     2  1:new 1:unknown
bgr2             ACPI fixes                                    4 *4:unknown
blob             [0/4] bloblist: fdt: Clean up the code        5  4:changes 1:unknown
bmg              buildman: Correct behaviour of --in-tree      2  2:new
ci-lab           CI multi-processing                           1  1:n/a
cia              CI improvements                               1  1:changes
efiq3            [v3,00/29] arm: Support building as an EF    36  32:changes 4:unknown
efit             efi: Rename the lib/efi directory             4  4:new
expa             expo: Allow the nominal display-size to b     6  6:n/a
fast             emulation: Improve support for booting fr    19  19:unknown

Series Management Commands

The series subcommand offers a comprehensive set of operations:

Core Operations

add: Add a new series to tracking
send: Send patches (like patman send but for any tracked series)
ls: List all tracked series
scan: Rescan a branch to update patch information

Version Management

inc: Create next version (v2, v3, etc.) by creating a new branch
dec: Delete current version and branch
rm-version: Remove specific versions
rm: Remove entire series

Patchwork Integration

autolink: Find Patchwork link for your series
progress: Show upstream status and review progress
gather: Collect review tags from Patchwork into commits
open: Open series in web browser

Advanced Features

mark/unmark: Add/remove Change-Id tags for better patch tracking
archive/unarchive: Archive completed series (creates dated tags, deletes branches)
patches: Show patches in a specific series/version

Advanced Workflow Example

Here’s how the series feature shines in a real-world scenario:

Initial submission:

   git checkout my-feature
   patman series add -m  # Mark commits with Change-Ids
   patman series send

Address review feedback:

   patman series inc  # Creates my-feature-v2 branch
   # Make your changes...
   patman series send

Track progress:

   patman series progress  # Shows review status
   patman series gather -Cc   # Pulls in Reviewed-by tags, shows comments

Final acceptance:

   patman series archive  # Clean up, create tags

Database-Driven Benefits

The series feature maintains a SQLite database (typically in ~/.config/patman/) that persistently tracks:

Series metadata and descriptions
Version relationships between branches
Patchwork links and IDs
Patch Change-Ids for reliable tracking
Review status and gathered tags

This database approach means you can switch between projects, reboot your machine, or work on multiple series simultaneously without losing context.

Integration with Existing Workflows

The beauty of patman series is that it builds on top of the existing patman functionality you already know. All the same commit tags (Series-to, Series-cc, etc.) work exactly as before. The series feature simply adds persistent tracking and automation on top.

You can still use regular patman send for quick one-off patches, while leveraging patman series for more complex, multi-version patch series that need ongoing management.

Migration from Manual Workflows

If you’re currently managing patch series manually with git branches and spreadsheets, migrating to patman series is straightforward:

Use patman series add on your existing branches
Let patman discover Patchwork links with patman series autolink-all
Start using patman series send instead of manual git send-email

Conclusion

The patman series feature represents a significant evolution in patch management tooling. By providing database-backed series tracking with deep Patchwork integration, it eliminates much of the manual bookkeeping that makes contributing to large projects tedious.

Whether you’re a seasoned contributor juggling multiple patch series or a newcomer looking to streamline your workflow, patman series offers a compelling upgrade to the traditional patch-by-patch approach. The investment in learning these commands pays dividends in reduced errors, better organization, and more time spent on actual development rather than patch logistics.

Try incorporating patman series into your next contribution workflow – your future self will thank you when managing v4 of that complex patch series becomes as simple as patman series inc followed by patman series send.

The patman series feature is available in recent versions of U-Boot’s patman tool (pip install patch-manager). For complete documentation, see tools/patman/patman.rst in the U-Boot source tree, or here.