User Manual

Submitting patches

Initial Submission

Patches are normally submitted with git send-email to a mailing list. For instance, if we branched from master, have three patches to submit, we can use:

$ git send-email --to=<mailing-list> --cover-letter --annotate master

This command will produce the following email thread (providing you have the chainreplyto configuration option set to false):

+ [PATCH 0/3] Cover Letter Subject
+--> [PATCH 1/3] Patch 1
+--> [PATCH 2/3] Patch 2
+--> [PATCH 3/3] Patch 3

Patchwork receives those mails and construct Series and Patches objects to present a high level view of the mailing-list activity and a way to track what happens to that submission.

It’s a good idea to include a cover letter to introduce the work. Patchwork will also pick up that cover letter and name the series with the subject of that email.

When sending only one patch, it’s a bit much to send a cover letter along with it as the commit message should provide enough context. In that case, Patchwork will use the subject of the patch as the series title.

New Versions

Sometimes, maybe even more often than hoped, one needs to resend a few patches or even entire series to address review comments.

Patchwork supports:

  • Re-sending a single patch as a reply to the reviewer email. This is usually only used when a few patches have to be resent.
  • Re-sending a full series as a new thread.

A Series object in patchwork tracks all the changes on top of the initial submission.

New Patch

To send a v2 of a patch part of a bigger series, one would do something similar to:

$ git send-email --to=<mailing-list> --cc=<reviewer> \
                 --in-reply-to=<reviewer-mail-message-id> \
                 --reroll-count 2 -1 HEAD~2

And, continuing the previous example, this would result in the following email thread:

+ [PATCH 0/3] Cover Letter Subject
+--> [PATCH 1/3] Patch 1
+--> [PATCH 2/3] Patch 2
|  +--> Re: [PATCH 2/3] Patch 2               (reviewer comments)
|     +--> [PATCH v2 2/3] Patch 2             (v2 of patch 2/3)
+--> [PATCH 3/3] Patch 3

Patch work will create a new revision of the series, updating patch #2 to the new version of that patch.

New Series

When something is really wrong or when, to address the review, most patches of a series need to be revised, re-sending individual emails can be both annoying for the patch author but also hard to follow from the reviewer side. It’s then better to re-send a full new thread and forget the previous one.

Patchwork will get that and create a new revision of the initial series with all patches updated to the latest and greatest.

+ [PATCH 0/3] Cover Letter Subject
+--> [PATCH 1/3] Patch 1
+--> [PATCH 2/3] Patch 2
+--> [PATCH 3/3] Patch 3

+ [PATCH v2 0/3] Cover Letter Subject
+--> [PATCH v2 1/3] Patch 1                   (v2 of patch 1/3)
+--> [PATCH v2 2/3] Patch 2                   (v2 of patch 2/3)
+--> [PATCH v2 3/3] Patch 3                   (v2 of patch 3/3)

Patchwork uses the cover letter subject to detect that intent. So one doesn’t need to use the reroll-count like above, the following would work as well:

+ [PATCH 0/3] Cover Letter Subject
+--> [PATCH 1/3] Patch 1
+--> [PATCH 2/3] Patch 2
+--> [PATCH 3/3] Patch 3

+ [PATCH 0/3] Cover Letter Subject (v2)
+--> [PATCH 1/3] Patch 1                     (v2 of patch 1/3)
+--> [PATCH 2/3] Patch 2                     (v2 of patch 2/3)
+--> [PATCH 3/3] Patch 3                     (v2 of patch 3/3)

Of course, we’ve now entered a dangerous territory. Trying to parse some human-generated text. The regular expression used accepts several ways of saying that the series is a new version of a previous one. If your favourite way isn’t among what’s supported, consider contributing (like filing an issue)!

Considering an initial series with Awesome feature as the cover letter subject, Patchwork will considering series with the following cover letter subjects as new revisions:

Regular Expression Cover Letter
 
  • Awesome feature
  • awesome feature
[, \(]*(v|take)[\) 0-9]+$')
  • Awesome feature v2
  • awesome feature V2
  • Awesome feature, v3
  • Awesome feature (v4)
  • Awesome feature (take 5)
  • Awesome feature, take 6

git-pw

git-pw (or git pw) is a command line tool that bridges git and patchwork.

Installation

Requirements

git-pw uses GitPython and requests, so those dependencies need to be installed. Using the distribution packages should work.

On Fedora:

$ sudo dnf install GitPython python-requests

On Debian/Ubuntu:

$ sudo apt-get install python-git python-requests

Alternatively it’s possible to use pip. git-pw/requirements.txt in the patchwork git repository has the list of required packages:

$ cat git-pw/requirements.txt
GitPython
requests
$ pip install -r requirements.txt

Getting git-pw

git-pw can be directly downloaded from patchwork’s git repository, given execution permission (chmod +x) and put it anywhere in your PATH.

Because this tool is still very young and to easily get the latest version I would suggest cloning patchwork’s repository and use a symlink. This way, git-pw can be updated with a single git pull command. From patchwork’s checkout:

$ ln -s $PWD/git-pw/git-pw ~/.local/bin/

Setup

git-pw configuration is stored in git config files and so can be set per git repository. Two pieces of information are needed to get started: the URL of the patchwork instance and the project this git repository maps to.

For example, the following sets git-pw up for the intel-gfx project on freedesktop.org:

$ git config patchwork.default.url https://patchwork.freedesktop.org
$ git config patchwork.default.project intel-gfx

git-pw is ready to go! Applying a series known to patchwork to the current git tree is now a single command away:

$ git pw apply -s 122
Applying series: DP refactoring v2 (rev 1)
Applying: drm/i915: Don't pass *DP around to link training functions
Applying: drm/i915: Split write of pattern to DP reg from intel_dp_set_link_train
Applying: drm/i915 Call get_adjust_train() from clock recovery and channel eq
Applying: drm/i915: Move register write into intel_dp_set_signal_levels()
Applying: drm/i915: Move generic link training code to a separate file
...